provider

package
v1.4.0 Latest Latest
Warning

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

 Go to latest Published: Oct 20, 2026 License: Apache-2.0 Imports: 10 Imported by: 0

Documentation

Overview

Package provider defines the unified Fenced Provider Plugin Protocol. It allows Model, Tool, Memory, Browser, Storage, and Runtime providers to be developed, registered, and discovered without modifying the Kernel.

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrProviderNotFound    = errors.New("provider not found")
	ErrProviderExists      = errors.New("provider already registered")
	ErrInvalidProviderType = errors.New("invalid provider type")
)
View Source 
var DefaultRegistry = NewRegistry()

DefaultRegistry is the global in-process provider registry.

Functions

func Register 

func Register(p Provider) error

Register registers a provider with the DefaultRegistry.

Types

type BrowserConfig 

type BrowserConfig struct {
	Headless       bool `json:"headless"`
	TimeoutSeconds int  `json:"timeoutSeconds"`
	ViewportWidth  int  `json:"viewportWidth"`
	ViewportHeight int  `json:"viewportHeight"`
}

BrowserConfig holds configuration parameters for BrowserProvider.

type BrowserProvider 

type BrowserProvider interface {
	Provider
	Navigate(ctx context.Context, req NavigateRequest) (BrowserResponse, error)
	Screenshot(ctx context.Context, req ScreenshotRequest) ([]byte, error)
	Click(ctx context.Context, req ClickRequest) (BrowserResponse, error)
	Evaluate(ctx context.Context, req EvaluateRequest) (json.RawMessage, error)
}

BrowserProvider supplies web browsing, automation, and DOM interaction capabilities.

type BrowserProviderImpl 

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

BrowserProviderImpl implements BrowserProvider and ToolProvider.

func NewBrowserProvider 

func NewBrowserProvider(cfg BrowserConfig) (*BrowserProviderImpl, error)

NewBrowserProvider creates a new Browser Provider.

func (*BrowserProviderImpl) Click 

func (p *BrowserProviderImpl) Click(ctx context.Context, req ClickRequest) (BrowserResponse, error)

func (*BrowserProviderImpl) Close 

func (p *BrowserProviderImpl) Close() error

func (*BrowserProviderImpl) Evaluate 

func (p *BrowserProviderImpl) Evaluate(ctx context.Context, req EvaluateRequest) (json.RawMessage, error)

func (*BrowserProviderImpl) Health 

func (p *BrowserProviderImpl) Health(ctx context.Context) HealthStatus

func (*BrowserProviderImpl) InvokeTool 

func (p *BrowserProviderImpl) InvokeTool(ctx context.Context, req ToolInvocationRequest) (ToolInvocationResult, error)

func (*BrowserProviderImpl) ListTools 

func (p *BrowserProviderImpl) ListTools(ctx context.Context) ([]ToolDefinition, error)

ToolProvider methods: exposes browser as callable tools for agents.

func (*BrowserProviderImpl) Manifest 

func (p *BrowserProviderImpl) Manifest() Manifest

func (*BrowserProviderImpl) Navigate 

func (p *BrowserProviderImpl) Navigate(ctx context.Context, req NavigateRequest) (BrowserResponse, error)

func (*BrowserProviderImpl) Screenshot 

func (p *BrowserProviderImpl) Screenshot(ctx context.Context, req ScreenshotRequest) ([]byte, error)

type BrowserResponse 

type BrowserResponse struct {
	URL        string `json:"url"`
	StatusCode int    `json:"statusCode"`
	Title      string `json:"title,omitempty"`
	Content    string `json:"content,omitempty"`
}

BrowserResponse returns the page navigation or evaluation outcome.

type ClickRequest 

type ClickRequest struct {
	Selector string `json:"selector"`
	Timeout  int    `json:"timeout,omitempty"`
}

ClickRequest requests clicking an element by CSS or XPath selector.

type EvaluateRequest 

type EvaluateRequest struct {
	Script string `json:"script"`
}

EvaluateRequest executes JavaScript in the browser context.

type FunctionCall 

type FunctionCall struct {
	Name      string          `json:"name"`
	Arguments json.RawMessage `json:"arguments"`
}

FunctionCall describes the function and JSON arguments.

type GenerateRequest 

type GenerateRequest struct {
	Model       string           `json:"model"`
	Messages    []Message        `json:"messages"`
	Temperature float32          `json:"temperature,omitempty"`
	MaxTokens   int              `json:"maxTokens,omitempty"`
	Tools       []ToolDefinition `json:"tools,omitempty"`
	Stop        []string         `json:"stop,omitempty"`
}

GenerateRequest defines inputs to a language model invocation.

type GenerateResponse 

type GenerateResponse struct {
	ID           string  `json:"id"`
	Model        string  `json:"model"`
	Message      Message `json:"message"`
	Usage        Usage   `json:"usage"`
	FinishReason string  `json:"finishReason"` // stop, length, tool_calls
}

GenerateResponse captures the completion result.

type HealthStatus 

type HealthStatus struct {
	Status    string             `json:"status"` // HEALTHY, DEGRADED, UNHEALTHY
	Message   string             `json:"message,omitempty"`
	Timestamp time.Time          `json:"timestamp"`
	Metrics   map[string]float64 `json:"metrics,omitempty"`
}

HealthStatus reports the operational state of a provider.

type Manifest 

type Manifest struct {
	Name                 string               `json:"name"`
	Version              string               `json:"version"`
	Type                 ProviderType         `json:"type"`
	Capabilities         []string             `json:"capabilities"`
	ConfigSchema         json.RawMessage      `json:"configSchema,omitempty"`
	Secrets              []string             `json:"secrets,omitempty"`
	ResourceRequirements ResourceRequirements `json:"resourceRequirements,omitempty"`
}

Manifest defines the formal metadata contract every Provider must declare.

func List 

func List(providerType ProviderType) []Manifest

List lists manifests from the DefaultRegistry.

func (Manifest) Validate 

func (m Manifest) Validate() error

Validate checks the structural integrity of the provider manifest.

type MemoryEntry 

type MemoryEntry struct {
	Key       string          `json:"key"`
	Value     json.RawMessage `json:"value"`
	Embedding []float32       `json:"embedding,omitempty"`
	Namespace string          `json:"namespace,omitempty"`
	CreatedAt time.Time       `json:"createdAt"`
	UpdatedAt time.Time       `json:"updatedAt"`
}

MemoryEntry represents a persistent key-value memory item with optional vector embedding.

type MemoryProvider 

type MemoryProvider interface {
	Provider
	Put(ctx context.Context, req MemoryPutRequest) error
	Get(ctx context.Context, namespace, key string) (MemoryEntry, error)
	Delete(ctx context.Context, namespace, key string) error
	Search(ctx context.Context, query MemorySearchQuery) ([]MemorySearchResult, error)
}

MemoryProvider supplies persistent and vector memory for agents.

type MemoryPutRequest 

type MemoryPutRequest struct {
	Namespace string          `json:"namespace,omitempty"`
	Key       string          `json:"key"`
	Value     json.RawMessage `json:"value"`
	Embedding []float32       `json:"embedding,omitempty"`
	TTL       time.Duration   `json:"ttl,omitempty"`
}

MemoryPutRequest stores or updates a memory entry.

type MemorySearchQuery 

type MemorySearchQuery struct {
	Namespace   string    `json:"namespace,omitempty"`
	QueryVector []float32 `json:"queryVector,omitempty"`
	Prefix      string    `json:"prefix,omitempty"`
	Limit       int       `json:"limit,omitempty"`
	MinScore    float32   `json:"minScore,omitempty"`
}

MemorySearchQuery queries semantic memory via vector similarity or prefix matching.

type MemorySearchResult 

type MemorySearchResult struct {
	Entry MemoryEntry `json:"entry"`
	Score float32     `json:"score"`
}

MemorySearchResult returns a matching entry with its similarity score.

type Message 

type Message struct {
	Role      string     `json:"role"` // system, user, assistant, tool
	Content   string     `json:"content"`
	Name      string     `json:"name,omitempty"`
	ToolCalls []ToolCall `json:"toolCalls,omitempty"`
}

Message represents a prompt turn in chat completions.

type ModelProvider 

type ModelProvider interface {
	Provider
	Generate(ctx context.Context, req GenerateRequest) (GenerateResponse, error)
	Stream(ctx context.Context, req GenerateRequest, onChunk func(StreamChunk) error) error
}

ModelProvider provides text generation and streaming model capabilities. 

type NavigateRequest struct {
	URL            string `json:"url"`
	WaitUntil      string `json:"waitUntil,omitempty"` // load, domcontentloaded, networkidle
	TimeoutSeconds int    `json:"timeoutSeconds,omitempty"`
}

NavigateRequest requests navigating the browser to a URL.

type ObjectMetadata 

type ObjectMetadata struct {
	Key          string            `json:"key"`
	Size         int64             `json:"size"`
	ETag         string            `json:"etag"`
	ContentType  string            `json:"contentType"`
	LastModified time.Time         `json:"lastModified"`
	CustomMeta   map[string]string `json:"customMeta,omitempty"`
}

ObjectMetadata describes an artifact stored in object storage.

type OpenAIConfig 

type OpenAIConfig struct {
	APIKey         string  `json:"apiKey"`
	Model          string  `json:"model"`
	BaseURL        string  `json:"baseUrl,omitempty"`
	DefaultTemp    float32 `json:"defaultTemp,omitempty"`
	MaxTokens      int     `json:"maxTokens,omitempty"`
	RequestTimeout int     `json:"requestTimeoutSeconds,omitempty"`
}

OpenAIConfig holds configuration parameters for OpenAIProvider.

type OpenAIProvider 

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

OpenAIProvider implements ModelProvider for OpenAI-compatible LLM endpoints.

func NewOpenAIProvider 

func NewOpenAIProvider(cfg OpenAIConfig) (*OpenAIProvider, error)

NewOpenAIProvider instantiates a production-ready OpenAI model provider.

func (*OpenAIProvider) Close 

func (p *OpenAIProvider) Close() error

func (*OpenAIProvider) Generate 

func (p *OpenAIProvider) Generate(ctx context.Context, req GenerateRequest) (GenerateResponse, error)

func (*OpenAIProvider) Health 

func (p *OpenAIProvider) Health(ctx context.Context) HealthStatus

func (*OpenAIProvider) Manifest 

func (p *OpenAIProvider) Manifest() Manifest

func (*OpenAIProvider) Stream 

func (p *OpenAIProvider) Stream(ctx context.Context, req GenerateRequest, onChunk func(StreamChunk) error) error

type PostgresMemoryConfig 

type PostgresMemoryConfig struct {
	ConnectionString string `json:"connectionString"`
	Table            string `json:"table"`
	VectorDimensions int    `json:"vectorDimensions"`
	DistanceMetric   string `json:"distanceMetric,omitempty"` // cosine, l2, inner_product
}

PostgresMemoryConfig holds configuration parameters for PostgresMemoryProvider.

type PostgresMemoryProvider 

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

PostgresMemoryProvider implements MemoryProvider for PostgreSQL + pgvector.

func NewPostgresMemoryProvider 

func NewPostgresMemoryProvider(cfg PostgresMemoryConfig) (*PostgresMemoryProvider, error)

NewPostgresMemoryProvider instantiates a new PostgreSQL memory and vector provider.

func (*PostgresMemoryProvider) Close 

func (p *PostgresMemoryProvider) Close() error

func (*PostgresMemoryProvider) Delete 

func (p *PostgresMemoryProvider) Delete(ctx context.Context, namespace, key string) error

func (*PostgresMemoryProvider) Get 

func (p *PostgresMemoryProvider) Get(ctx context.Context, namespace, key string) (MemoryEntry, error)

func (*PostgresMemoryProvider) Health 

func (p *PostgresMemoryProvider) Health(ctx context.Context) HealthStatus

func (*PostgresMemoryProvider) Manifest 

func (p *PostgresMemoryProvider) Manifest() Manifest

func (*PostgresMemoryProvider) Put 

func (p *PostgresMemoryProvider) Put(ctx context.Context, req MemoryPutRequest) error

func (*PostgresMemoryProvider) Search 

func (p *PostgresMemoryProvider) Search(ctx context.Context, query MemorySearchQuery) ([]MemorySearchResult, error)

type Provider 

type Provider interface {
	Manifest() Manifest
	Health(ctx context.Context) HealthStatus
	Close() error
}

Provider is the base interface implemented by all Fenced providers.

func Get 

func Get(providerType ProviderType, name string) (Provider, error)

Get retrieves a provider from the DefaultRegistry.

type ProviderType 

type ProviderType string

ProviderType identifies the category of capability a provider supplies. 

const (
	TypeModel   ProviderType = "model"
	TypeTool    ProviderType = "tool"
	TypeMemory  ProviderType = "memory"
	TypeBrowser ProviderType = "browser"
	TypeStorage ProviderType = "storage"
	TypeRuntime ProviderType = "runtime"
)

type Registry 

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

Registry manages the set of available providers across all categories.

func NewRegistry 

func NewRegistry() *Registry

NewRegistry initializes a clean, thread-safe Provider Registry.

func (*Registry) CheckAllHealth 

func (r *Registry) CheckAllHealth(ctx context.Context) map[string]HealthStatus

CheckAllHealth queries the operational health of all registered providers.

func (*Registry) Get 

func (r *Registry) Get(providerType ProviderType, name string) (Provider, error)

Get retrieves a provider by type and name.

func (*Registry) List 

func (r *Registry) List(providerType ProviderType) []Manifest

List returns manifests of all providers matching the given type, or all if empty.

func (*Registry) Register 

func (r *Registry) Register(p Provider) error

Register adds a provider to the registry after validating its manifest.

type ResourceRequirements 

type ResourceRequirements struct {
	CPU     string `json:"cpu,omitempty"`     // e.g. "500m", "2"
	Memory  string `json:"memory,omitempty"`  // e.g. "512Mi", "4Gi"
	GPU     string `json:"gpu,omitempty"`     // e.g. "1" (NVIDIA / Metal)
	Storage string `json:"storage,omitempty"` // e.g. "10Gi"
}

ResourceRequirements declares CPU, memory, and acceleration needed by the provider.

type RuntimeProvider 

type RuntimeProvider interface {
	Provider
	StartInstance(ctx context.Context, req RuntimeStartRequest) (RuntimeStartResponse, error)
	StopInstance(ctx context.Context, executionID string, gracePeriod time.Duration) error
	InspectInstance(ctx context.Context, executionID string) (RuntimeStatusResponse, error)
	StreamLogs(ctx context.Context, executionID string, onLog func(entry string) error) error
	CaptureSnapshot(ctx context.Context, executionID string) (json.RawMessage, error)
	RestoreSnapshot(ctx context.Context, executionID string, state json.RawMessage) error
}

RuntimeProvider launches and supervises isolated agent execution sandboxes.

type RuntimeStartRequest 

type RuntimeStartRequest struct {
	ExecutionID     string               `json:"executionId"`
	ImageOrArtifact string               `json:"imageOrArtifact"`
	Environment     map[string]string    `json:"environment,omitempty"`
	ResourceLimits  ResourceRequirements `json:"resourceLimits,omitempty"`
	Entrypoint      []string             `json:"entrypoint,omitempty"`
}

RuntimeStartRequest specifies the container, binary, or WASM component to launch.

type RuntimeStartResponse 

type RuntimeStartResponse struct {
	ExecutionID string    `json:"executionId"`
	ContainerID string    `json:"containerId,omitempty"`
	StartedAt   time.Time `json:"startedAt"`
}

RuntimeStartResponse returns launch metadata.

type RuntimeStatusResponse 

type RuntimeStatusResponse struct {
	ExecutionID   string             `json:"executionId"`
	State         string             `json:"state"` // RUNNING, STOPPED, FAILED
	ExitCode      int                `json:"exitCode,omitempty"`
	ResourceUsage map[string]float64 `json:"resourceUsage,omitempty"`
}

RuntimeStatusResponse returns current execution health.

type ScreenshotRequest 

type ScreenshotRequest struct {
	FullPage bool   `json:"fullPage,omitempty"`
	Format   string `json:"format,omitempty"` // png, jpeg
	Quality  int    `json:"quality,omitempty"`
}

ScreenshotRequest captures a page screenshot.

type StorageProvider 

type StorageProvider interface {
	Provider
	PutObject(ctx context.Context, key string, data io.Reader, size int64, contentType string) (ObjectMetadata, error)
	GetObject(ctx context.Context, key string) (io.ReadCloser, ObjectMetadata, error)
	DeleteObject(ctx context.Context, key string) error
	ListObjects(ctx context.Context, prefix string, limit int) ([]ObjectMetadata, error)
}

StorageProvider supplies object, file, and artifact persistence.

type StreamChunk 

type StreamChunk struct {
	ID           string     `json:"id"`
	DeltaContent string     `json:"deltaContent,omitempty"`
	ToolCalls    []ToolCall `json:"toolCalls,omitempty"`
	FinishReason string     `json:"finishReason,omitempty"`
}

StreamChunk conveys one delta in streaming model execution.

type ToolCall 

type ToolCall struct {
	ID       string       `json:"id"`
	Type     string       `json:"type"` // function
	Function FunctionCall `json:"function"`
}

ToolCall represents an assistant-requested tool invocation.

type ToolDefinition 

type ToolDefinition struct {
	Name        string          `json:"name"`
	Description string          `json:"description"`
	InputSchema json.RawMessage `json:"inputSchema"`
}

ToolDefinition describes an executable tool and its input schema.

type ToolInvocationRequest 

type ToolInvocationRequest struct {
	ToolName    string          `json:"toolName"`
	Arguments   json.RawMessage `json:"arguments"`
	ExecutionID string          `json:"executionId,omitempty"`
}

ToolInvocationRequest contains the arguments for a tool call.

type ToolInvocationResult 

type ToolInvocationResult struct {
	Output    json.RawMessage `json:"output"`
	ReceiptID string          `json:"receiptId,omitempty"`
	Error     string          `json:"error,omitempty"`
}

ToolInvocationResult contains the tool's execution outcome and audit receipt.

type ToolProvider 

type ToolProvider interface {
	Provider
	ListTools(ctx context.Context) ([]ToolDefinition, error)
	InvokeTool(ctx context.Context, req ToolInvocationRequest) (ToolInvocationResult, error)
}

ToolProvider supplies capabilities and tools callable by agents.

type Usage 

type Usage struct {
	PromptTokens     int `json:"promptTokens"`
	CompletionTokens int `json:"completionTokens"`
	TotalTokens      int `json:"totalTokens"`
}

Usage reports token consumption for budget accounting.

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.