Documentation
¶
Overview ¶
Package source defines the SPI for read-only source connectors.
A source connector retrieves context from an external system (Slack, GitHub, Google Calendar, etc.) for use in draft generation. Unlike the connector package (which executes approved, irreversible actions), source connectors are read-only and require no approval flow. Credentials come from connected accounts.
Each source connector exposes a set of tools that an LLM can call during draft generation. Tool definitions are LLM-agnostic — they can be converted to any LLM's function calling format by a thin adapter layer.
Index ¶
- Variables
- func WithTokenSaver(ctx context.Context, saver TokenSaver) context.Context
- type AuthFailedError
- type PersistingTokenSource
- type Registry
- func (r *Registry) AllTools() []ToolDefinition
- func (r *Registry) ExecuteTool(ctx context.Context, tool string, params map[string]any, token []byte) (map[string]any, error)
- func (r *Registry) Get(provider string) (SourceConnector, bool)
- func (r *Registry) Providers() []string
- func (r *Registry) Register(sc SourceConnector)
- func (r *Registry) ResolveToolProvider(tool string) (string, error)
- func (r *Registry) ToolsForProvider(provider string) []ToolDefinition
- type SourceConnector
- type TokenSaver
- type ToolDefinition
- type ToolParam
Constants ¶
This section is empty.
Variables ¶
var ErrAuthFailed = errors.New("source: authentication failed")
ErrAuthFailed indicates that a connector's credentials are invalid, expired, or revoked. Used as a sentinel for errors.Is checks.
Functions ¶
func WithTokenSaver ¶
func WithTokenSaver(ctx context.Context, saver TokenSaver) context.Context
WithTokenSaver returns a context carrying a TokenSaver callback. Connectors that support automatic token refresh call the saver when the underlying oauth2.TokenSource returns a new token.
Types ¶
type AuthFailedError ¶
type AuthFailedError struct {
Providers []string // deduplicated provider names that failed
}
AuthFailedError is a structured error that carries the names of providers whose credentials failed. Use errors.Is(err, ErrAuthFailed) to detect it, then errors.As(err, &authErr) to extract the provider list.
func (*AuthFailedError) Error ¶
func (e *AuthFailedError) Error() string
func (*AuthFailedError) Unwrap ¶
func (e *AuthFailedError) Unwrap() error
type PersistingTokenSource ¶
type PersistingTokenSource struct {
// contains filtered or unexported fields
}
PersistingTokenSource wraps an oauth2.TokenSource and calls a TokenSaver when a refresh produces a new token. This ensures rotated refresh tokens are written back to the vault so they survive across requests.
func NewPersistingTokenSource ¶
func NewPersistingTokenSource(base oauth2.TokenSource, original *oauth2.Token, saver TokenSaver, ctx context.Context) *PersistingTokenSource
NewPersistingTokenSource wraps base so that the first token refresh triggers a save via saver. The original token is used to detect whether a refresh actually occurred (by comparing access tokens).
func (*PersistingTokenSource) Token ¶
func (p *PersistingTokenSource) Token() (*oauth2.Token, error)
Token returns the current token, persisting it to the vault if a refresh occurred. Vault write failures are logged but do not fail the API call — the refreshed token is still valid in memory for this request.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry holds registered source connectors and routes tool calls to the correct connector. It is safe for concurrent read access after initial registration.
func NewRegistry ¶
func NewRegistry() *Registry
NewRegistry creates an empty source connector registry.
func (*Registry) AllTools ¶
func (r *Registry) AllTools() []ToolDefinition
AllTools returns tool definitions across all registered connectors.
func (*Registry) ExecuteTool ¶
func (r *Registry) ExecuteTool(ctx context.Context, tool string, params map[string]any, token []byte) (map[string]any, error)
ExecuteTool resolves a tool to its connector and executes it.
func (*Registry) Get ¶
func (r *Registry) Get(provider string) (SourceConnector, bool)
Get returns the source connector for the given provider.
func (*Registry) Register ¶
func (r *Registry) Register(sc SourceConnector)
Register adds a source connector and indexes its tools.
func (*Registry) ResolveToolProvider ¶
ResolveToolProvider returns the provider name for a given tool.
func (*Registry) ToolsForProvider ¶
func (r *Registry) ToolsForProvider(provider string) []ToolDefinition
ToolsForProvider returns tool definitions for a specific provider.
type SourceConnector ¶
type SourceConnector interface {
// Provider returns the provider name (e.g. "slack", "github").
Provider() string
// Tools returns the tool definitions this connector exposes.
Tools() []ToolDefinition
// Execute runs a tool by name with the given parameters and credential.
// The token is the user's OAuth token retrieved from the vault.
Execute(ctx context.Context, tool string, params map[string]any, token []byte) (map[string]any, error)
}
SourceConnector retrieves context from an external system.
type TokenSaver ¶
TokenSaver persists a refreshed OAuth token back to the vault.
func GetTokenSaver ¶
func GetTokenSaver(ctx context.Context) TokenSaver
GetTokenSaver retrieves the TokenSaver from the context, or nil if none.
type ToolDefinition ¶
type ToolDefinition struct {
// Name is the tool identifier (e.g. "slack_channel_history").
Name string `json:"name"`
// Description is a human-readable explanation for the LLM.
Description string `json:"description"`
// Parameters describes the expected input parameters.
Parameters []ToolParam `json:"parameters"`
}
ToolDefinition describes a tool that an LLM can call for context retrieval.
type ToolParam ¶
type ToolParam struct {
// Name is the parameter name.
Name string `json:"name"`
// Type is the parameter type ("string", "integer", "boolean").
Type string `json:"type"`
// Description explains the parameter to the LLM.
Description string `json:"description"`
// Required indicates whether the parameter must be provided.
Required bool `json:"required"`
}
ToolParam describes a single parameter for a tool.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package calendar implements a SourceConnector for Google Calendar, providing read-only tools for checking events and availability.
|
Package calendar implements a SourceConnector for Google Calendar, providing read-only tools for checking events and availability. |
|
Package github implements a SourceConnector for GitHub, providing read-only tools for searching code, issues/PRs, getting PR details and diffs, and reading file contents.
|
Package github implements a SourceConnector for GitHub, providing read-only tools for searching code, issues/PRs, getting PR details and diffs, and reading file contents. |
|
Package gmail implements a SourceConnector for Gmail and Google Drive, providing read-only tools for searching emails, reading threads, searching Drive files, and reading document contents.
|
Package gmail implements a SourceConnector for Gmail and Google Drive, providing read-only tools for searching emails, reading threads, searching Drive files, and reading document contents. |