builtins

package
v0.2.1 Latest Latest
Warning

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

 Go to latest Published: Aug 30, 2026 License: Apache-2.0 Imports: 26 Imported by: 0

Documentation

Overview

Package builtins is the host-facing battery pack for Tacklr.

Optional tools (email, Exa web search) are constructed here with the same constructor-closure pattern as host tools. Add the results to AgentOptions.Tools. The harness does not inject them from AgentOptions fields. Planning and child-session tools stay harness-owned.

The OpenAI-compatible model client lives here and implements tacklr.InferenceStrategy. The harness interface stays on package tacklr.

VFS backend constructors live here so a host builds a /workspace tree from one import. Tree, At, Union, MountSession, and Provider stay in package vfs. brain.Open stays in package brain.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrIncompleteStream means a provider closed without a terminal response event.
	ErrIncompleteStream = errors.New("incomplete provider stream")
	// ErrMalformedStream means a provider emitted invalid SSE event JSON.
	ErrMalformedStream = errors.New("malformed provider stream")
)
View Source 
var (
	Local           = vfs.Local
	Memory          = vfs.Memory
	S3              = vfs.S3
	Blob            = vfs.Blob
	Drive           = vfs.Drive
	DriveWith       = vfs.DriveWith
	Graph           = vfs.Graph
	NewGoogleDrive  = vfs.NewGoogleDrive
	NewGoogleDocs   = vfs.NewGoogleDocs
	NewGoogleSheets = vfs.NewGoogleSheets
	NewGraph        = vfs.NewGraph
)
View Source 
var ErrService = errors.New("service failed")

ErrService is a host/network/auth/rate-limit failure (not a model-fixable query).

Functions

func ReadInbox 

func ReadInbox(provider EmailProvider) *tacklr.Tool

ReadInbox returns the read_inbox tool closed over provider.

func SendEmail 

func SendEmail(provider EmailProvider) *tacklr.Tool

SendEmail returns the permission-gated send_email tool closed over provider.

func WebFetch 

func WebFetch(client *Exa) *tacklr.Tool

func WebSearch 

func WebSearch(client *Exa) *tacklr.Tool

Types

type APIStatusError 

type APIStatusError struct {
	Status int
	Body   string
	Code   string
}

APIStatusError conveys an HTTP error response from an upstream LLM API. Use errors.As to extract structured status/body details from a wrapped chain.

func (*APIStatusError) Error 

func (e *APIStatusError) Error() string

func (*APIStatusError) ProviderErrorCode 

func (e *APIStatusError) ProviderErrorCode() string

ProviderErrorCode implements tacklr.ProviderStatus.

func (*APIStatusError) ProviderHTTPStatus 

func (e *APIStatusError) ProviderHTTPStatus() int

ProviderHTTPStatus implements tacklr.ProviderStatus.

type AWSS3 

type AWSS3 = vfs.AWSS3

SDK adapters hosts pass to S3 and Blob.

type AzureBlob 

type AzureBlob = vfs.AzureBlob

SDK adapters hosts pass to S3 and Blob.

type ContentsOptions 

type ContentsOptions struct {
	Highlights  any  `json:"highlights,omitempty"` // bool or HighlightsOptions
	Text        any  `json:"text,omitempty"`       // bool or TextOptions
	MaxAgeHours *int `json:"maxAgeHours,omitempty"`
}

ContentsOptions controls extraction and freshness on each result.

type ContentsRequest 

type ContentsRequest struct {
	URLs        []string `json:"urls,omitempty"`
	IDs         []string `json:"ids,omitempty"`
	Text        any      `json:"text,omitempty"`       // bool or TextOptions
	Highlights  any      `json:"highlights,omitempty"` // bool or HighlightsOptions
	MaxAgeHours *int     `json:"maxAgeHours,omitempty"`
}

ContentsRequest is POST /contents (known URLs or prior result ids). Provide urls or ids, not both. Content options are top-level (not nested).

type ContentsResponse 

type ContentsResponse struct {
	RequestID string              `json:"requestId"`
	Results   []SearchResult      `json:"results"`
	Statuses  []ContentsURLStatus `json:"statuses,omitempty"`
}

ContentsResponse is the body for a successful POST /contents call.

type ContentsURLStatus 

type ContentsURLStatus struct {
	ID     string `json:"id"`
	Status string `json:"status"` // success | error
	Source string `json:"source,omitempty"`
	Error  *struct {
		Tag            string `json:"tag,omitempty"`
		HTTPStatusCode *int   `json:"httpStatusCode,omitempty"`
	} `json:"error,omitempty"`
}

ContentsURLStatus reports per-URL fetch outcome from /contents.

type EmailProvider 

type EmailProvider interface {
	Kind() ProviderKind
	Validate(context.Context) error
	ReadInbox(context.Context, ReadInboxRequest) (Inbox, error)
	SendEmail(context.Context, SendEmailRequest) (SentEmail, error)
}

EmailProvider supplies the operations exposed by the built-in email tools. Implementations own authentication and provider-specific API behavior and must support concurrent calls when an agent uses workers.

func Gmail 

func Gmail(service *googlemail.Service) EmailProvider

Gmail returns an EmailProvider backed by the official Gmail SDK. Construct the service with the OAuth scopes the host permits.

func Outlook 

func Outlook(client *msgraphsdk.GraphServiceClient) EmailProvider

Outlook returns an EmailProvider backed by the official Graph SDK. The host constructs the client with the scopes and authentication flow it permits.

type Exa 

type Exa struct {
	APIKey     string
	BaseURL    string
	HTTPClient *http.Client
}

Exa calls Exa’s Search and Contents APIs.

func NewExa 

func NewExa(apiKey string) *Exa

NewExa builds a client for the given API key.

func (*Exa) Contents 

func (c *Exa) Contents(ctx context.Context, req ContentsRequest) (*ContentsResponse, error)

Contents performs POST /contents for known URLs (or prior result ids). Provide at least one of URLs or IDs.

func (*Exa) Search 

func (c *Exa) Search(ctx context.Context, req SearchRequest) (*SearchResponse, error)

Search performs POST /search. req.Query must be non-empty.

type HighlightsOptions 

type HighlightsOptions struct {
	Query         string `json:"query,omitempty"`
	MaxCharacters int    `json:"maxCharacters,omitempty"`
}

HighlightsOptions steers highlight extraction.

type Inbox 

type Inbox struct {
	Messages   []Message `json:"messages"`
	NextCursor string    `json:"next_cursor,omitempty"`
}

Inbox is one provider page of messages.

type Message 

type Message struct {
	ID         string    `json:"id"`
	ThreadID   string    `json:"thread_id,omitempty"`
	From       string    `json:"from"`
	To         []string  `json:"to,omitempty"`
	CC         []string  `json:"cc,omitempty"`
	Subject    string    `json:"subject,omitempty"`
	Body       string    `json:"body,omitempty"`
	ReceivedAt time.Time `json:"received_at"`
	Unread     bool      `json:"unread"`
}

Message is a provider-neutral email returned to the agent.

type OpenAIInferenceStrategy 

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

func NewOpenAIInferenceStrategy 

func NewOpenAIInferenceStrategy(client *http.Client) *OpenAIInferenceStrategy

func (*OpenAIInferenceStrategy) CountTokens 

func (s *OpenAIInferenceStrategy) CountTokens(ctx context.Context, messages []*tacklr.Message, tools []*tacklr.Tool) (int, error)

func (*OpenAIInferenceStrategy) Invoke 

func (s *OpenAIInferenceStrategy) Invoke(ctx context.Context, messages []*tacklr.Message, tools []*tacklr.Tool, systemPrompt string) (chan tacklr.LLMResponseChunk, error)

func (*OpenAIInferenceStrategy) MaxContextWindow 

func (s *OpenAIInferenceStrategy) MaxContextWindow() (int, error)

func (*OpenAIInferenceStrategy) ModelTelemetryIdentity 

func (s *OpenAIInferenceStrategy) ModelTelemetryIdentity() telemetry.ModelIdentity

ModelTelemetryIdentity implements the optional harness hook so model spans get GenAI provider/model attrs without exporting raw config fields.

func (*OpenAIInferenceStrategy) SetSystemPrompt 

func (s *OpenAIInferenceStrategy) SetSystemPrompt(prompt string)

func (*OpenAIInferenceStrategy) SupportsMIME 

func (s *OpenAIInferenceStrategy) SupportsMIME(mimeType string) bool

SupportsMIME implements tacklr.InferenceStrategy for the selected model id.

func (*OpenAIInferenceStrategy) WithApiKey 

func (s *OpenAIInferenceStrategy) WithApiKey(key string) *OpenAIInferenceStrategy

func (*OpenAIInferenceStrategy) WithLocalTokenFallback 

func (s *OpenAIInferenceStrategy) WithLocalTokenFallback() *OpenAIInferenceStrategy

WithLocalTokenFallback counts tokens with tiktoken when the provider returns 404/400/422 for /responses/input_tokens. Off by default.

func (*OpenAIInferenceStrategy) WithModel 

func (s *OpenAIInferenceStrategy) WithModel(model string) *OpenAIInferenceStrategy

func (*OpenAIInferenceStrategy) WithReasoningLevel 

func (s *OpenAIInferenceStrategy) WithReasoningLevel(level string) *OpenAIInferenceStrategy

func (*OpenAIInferenceStrategy) WithReasoningSummary 

func (s *OpenAIInferenceStrategy) WithReasoningSummary(summary string) *OpenAIInferenceStrategy

WithReasoningSummary sets reasoning.summary on Responses API requests ("auto", "concise", "detailed"). Empty clears it.

func (*OpenAIInferenceStrategy) WithURL 

func (s *OpenAIInferenceStrategy) WithURL(url string) *OpenAIInferenceStrategy

type ProviderKind 

type ProviderKind string

ProviderKind identifies an email service implemented by a battery adapter. 

const (
	ProviderGmail   ProviderKind = "gmail"
	ProviderOutlook ProviderKind = "outlook"
)

type ReadInboxRequest 

type ReadInboxRequest struct {
	From           string `json:"from,omitempty"`
	To             string `json:"to,omitempty"`
	Subject        string `json:"subject,omitempty"`
	ReceivedAfter  string `json:"received_after,omitempty"`
	ReceivedBefore string `json:"received_before,omitempty"`
	HasAttachment  *bool  `json:"has_attachment,omitempty"`
	Mailbox        string `json:"mailbox,omitempty"`
	UnreadOnly     bool   `json:"unread_only,omitempty"`
	Limit          int    `json:"limit,omitempty"`
	Cursor         string `json:"cursor,omitempty"`
}

ReadInboxRequest selects messages from the configured inbox.

func (ReadInboxRequest) Validate 

func (r ReadInboxRequest) Validate() error

Validate checks portable inbox filter values. Dates use YYYY-MM-DD.

type SearchRequest 

type SearchRequest struct {
	Query              string           `json:"query"`
	Type               string           `json:"type,omitempty"`
	NumResults         int              `json:"numResults,omitempty"`
	Category           string           `json:"category,omitempty"`
	IncludeDomains     []string         `json:"includeDomains,omitempty"`
	ExcludeDomains     []string         `json:"excludeDomains,omitempty"`
	StartPublishedDate string           `json:"startPublishedDate,omitempty"`
	EndPublishedDate   string           `json:"endPublishedDate,omitempty"`
	UserLocation       string           `json:"userLocation,omitempty"`
	SystemPrompt       string           `json:"systemPrompt,omitempty"`
	Contents           *ContentsOptions `json:"contents,omitempty"`
}

SearchRequest is the subset of POST /search we use for agent tools. JSON names match Exa’s camelCase wire format.

type SearchResponse 

type SearchResponse struct {
	RequestID string           `json:"requestId"`
	Results   []SearchResult   `json:"results"`
	Output    *SynthesisOutput `json:"output,omitempty"`
}

SearchResponse is the JSON body for a successful non-streaming /search call.

type SearchResult 

type SearchResult struct {
	Title         string   `json:"title"`
	URL           string   `json:"url"`
	PublishedDate string   `json:"publishedDate,omitempty"`
	Author        string   `json:"author,omitempty"`
	ID            string   `json:"id,omitempty"`
	Text          string   `json:"text,omitempty"`
	Highlights    []string `json:"highlights,omitempty"`
	Summary       string   `json:"summary,omitempty"`
}

SearchResult is one hit from Exa.

type SendEmailRequest 

type SendEmailRequest struct {
	To               []string `json:"to"`
	CC               []string `json:"cc,omitempty"`
	BCC              []string `json:"bcc,omitempty"`
	Subject          string   `json:"subject"`
	Body             string   `json:"body"`
	ReplyToMessageID string   `json:"reply_to_message_id,omitempty"`
}

SendEmailRequest is an outbound email composed by an agent.

func (SendEmailRequest) Validate 

func (r SendEmailRequest) Validate() error

Validate checks the provider-neutral requirements for an outbound email.

type SentEmail 

type SentEmail struct {
	ID       string `json:"id"`
	ThreadID string `json:"thread_id,omitempty"`
}

SentEmail identifies the message accepted by the provider.

type StatusError 

type StatusError struct {
	Op     string
	Status int
	Body   string
}

StatusError is an Exa HTTP status. QueryFixable is a 4xx the model can correct (not 401/403/429). Those plus 5xx unwrap as ErrService.

func (*StatusError) Error 

func (e *StatusError) Error() string

func (*StatusError) PublicationDomain 

func (e *StatusError) PublicationDomain() bool

func (*StatusError) QueryFixable 

func (e *StatusError) QueryFixable() bool

func (*StatusError) Unwrap 

func (e *StatusError) Unwrap() error

type SynthesisOutput 

type SynthesisOutput struct {
	Content json.RawMessage `json:"content,omitempty"`
}

SynthesisOutput holds optional deep-search / schema synthesis. Content may be a string or a JSON object depending on outputSchema.

type TextOptions 

type TextOptions struct {
	MaxCharacters int    `json:"maxCharacters,omitempty"`
	Verbosity     string `json:"verbosity,omitempty"` // compact | standard | full
}

TextOptions steers full-page text extraction.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.