textsearch

type Config struct {
	// SearchTime defaults to [BeforeInvoke].
	SearchTime SearchBehavior

	// FunctionToolName names the on-demand search tool. Nil defaults to "Search".
	FunctionToolName *string

	// FunctionToolDescription describes the on-demand search tool. Nil uses
	// "Allows searching for additional information to help answer the user question.".
	FunctionToolDescription *string

	// ContextPrompt prefixes search results. Nil uses a default additional-context prompt.
	// An explicit empty string suppresses the prompt text.
	ContextPrompt *string

	// CitationsPrompt follows search results. Nil uses a default citation instruction.
	// An explicit empty string suppresses the instruction text.
	CitationsPrompt *string

	// ContextFormatter replaces the default formatting and ignores both prompts.
	// Automatic searches do not call the formatter for an empty result list;
	// on-demand searches do. Formatting errors are ignored during automatic
	// searches, logged when Logger is configured, and returned from the on-demand tool.
	ContextFormatter func([]Result) (string, error)

	// RecentMessageMemoryLimit is the maximum number of individual messages
	// retained in the session and prepended to automatic search queries.
	// Zero disables memory. Negative values are invalid.
	RecentMessageMemoryLimit int

	// RecentMessageRolesIncluded selects message roles retained in memory.
	// Nil defaults to user messages; an empty, non-nil slice retains no messages.
	// Roles are compared case-insensitively. The slice is retained, not copied;
	// do not modify it while the provider is in use. This does not filter the
	// current request's search input.
	RecentMessageRolesIncluded []message.Role

	// StateKey identifies provider state in the session. Nil defaults to
	// "TextSearchProvider". Explicit empty or whitespace-only keys are invalid.
	// Use distinct keys for providers that need independent memory.
	StateKey *string

	// SearchInputMessageFilter filters automatic search input.
	// Nil defaults to [messagefilter.ExternalOnly].
	SearchInputMessageFilter messagefilter.Filter

	// StorageInputRequestMessageFilter filters request messages before storing memory.
	// Nil defaults to [messagefilter.ExternalOnly].
	StorageInputRequestMessageFilter messagefilter.Filter

	// StorageInputResponseMessageFilter filters response messages before storing memory.
	// Nil passes all response messages through.
	StorageInputResponseMessageFilter messagefilter.Filter

	// Logger receives provider diagnostics. When nil, no diagnostics are logged.
	Logger *slog.Logger

	// LogSensitiveData includes raw queries and formatted results in debug logs.
	// The default is false. When true, Redactor is ignored.
	LogSensitiveData bool

	// Redactor transforms queries and formatted results in debug logs.
	// When nil and LogSensitiveData is false, they are replaced with "<redacted>".
	Redactor func(string) string
}

type Provider struct {
	// contains filtered or unexported fields
}

type Result struct {
	SourceName string
	SourceLink string
	Text       string

	// RawRepresentation retains the underlying search result for a custom formatter.
	RawRepresentation any
}

type SearchBehavior int

type State struct {
	// RecentMessagesText contains retained message texts in chronological order.
	// Nil means memory has not been populated; a non-nil empty slice is stored
	// as an empty JSON array.
	RecentMessagesText []string `json:"recentMessagesText,omitzero"`
}