suggestionbox

Documentation

Overview

Package suggestionbox provides a client for accessing Suggestionbox services.

Index

• type Choice
  • func NewChoice(id string, features ...Feature) Choice
• type Client
  • func New(addr string) *Client
  • func (c *Client) CreateModel(ctx context.Context, model Model) (Model, error)
  • func (c *Client) DeleteModel(ctx context.Context, modelID string) error
  • func (c *Client) GetModel(ctx context.Context, modelID string) (Model, error)
  • func (c *Client) GetModelStats(ctx context.Context, modelID string) (ModelStats, error)
  • func (c *Client) Info() (*boxutil.Info, error)
  • func (c *Client) ListModels(ctx context.Context) ([]Model, error)
  • func (c *Client) OpenState(ctx context.Context, modelID string) (io.ReadCloser, error)
  • func (c *Client) PostState(ctx context.Context, r io.Reader) (Model, error)
  • func (c *Client) PostStateURL(ctx context.Context, stateURL *url.URL) (Model, error)
  • func (c *Client) Predict(ctx context.Context, modelID string, request PredictRequest) (PredictResponse, error)
  • func (c *Client) Reward(ctx context.Context, modelID string, reward Reward) error
  • func (c *Client) SetClient(client *http.Client)
• type Feature
  • func FeatureImageBase64(key string, data string) Feature
  • func FeatureImageURL(key string, url string) Feature
  • func FeatureKeyword(key string, keyword string) Feature
  • func FeatureList(key string, keywords ...string) Feature
  • func FeatureNumber(key string, value float64) Feature
  • func FeatureText(key string, text string) Feature
• type Model
  • func NewModel(id, name string, choices ...Choice) Model
• type ModelOptions
• type ModelStats
• type PredictRequest
• type PredictResponse
• type Prediction
• type Reward

Types

type Choice

type Choice struct {
	// ID is a unique ID for this choice.
	ID string `json:"id"`
	// Features holds all the Feature objects that describe
	// this choice.
	Features []Feature `json:"features,omitempty"`
}

Choice is an option with features.

func NewChoice

func NewChoice(id string, features ...Feature) Choice

NewChoice creates a new Choice.

type Client

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

Client is an HTTP client that can make requests to the box.

func New

func New(addr string) *Client

New makes a new Client for the box at the specified address.

func (*Client) CreateModel

func (c *Client) CreateModel(ctx context.Context, model Model) (Model, error)

CreateModel creates the Model in Suggestionbox. If no ID is set, one will be assigned in the return Model.

func (*Client) DeleteModel

func (c *Client) DeleteModel(ctx context.Context, modelID string) error

DeleteModel gets a Model by its ID.

func (*Client) GetModel

func (c *Client) GetModel(ctx context.Context, modelID string) (Model, error)

GetModel gets a Model by its ID.

func (*Client) GetModelStats

func (c *Client) GetModelStats(ctx context.Context, modelID string) (ModelStats, error)

GetModelStats gets the statistics for the specified model.

func (*Client) Info

func (c *Client) Info() (*boxutil.Info, error)

Info gets the details about the box.

func (*Client) ListModels

func (c *Client) ListModels(ctx context.Context) ([]Model, error)

ListModels gets a Model by its ID.

func (*Client) OpenState

func (c *Client) OpenState(ctx context.Context, modelID string) (io.ReadCloser, error)

OpenState opens the state file for the specified model for reading. Clients must call Close.

func (*Client) PostState

func (c *Client) PostState(ctx context.Context, r io.Reader) (Model, error)

PostState uploads new state data and returns the Model that was contained in the state file.

func (*Client) PostStateURL

func (c *Client) PostStateURL(ctx context.Context, stateURL *url.URL) (Model, error)

PostStateURL tells Suggestionbox to download the state file specified by the URL and returns the Model that was contained in the state file.

func (*Client) Predict

func (c *Client) Predict(ctx context.Context, modelID string, request PredictRequest) (PredictResponse, error)

Predict asks a Model to make a prediction.

func (*Client) Reward

func (c *Client) Reward(ctx context.Context, modelID string, reward Reward) error

Reward tells Suggestionbox about a successful prediction.

func (*Client) SetClient

func (c *Client) SetClient(client *http.Client)

SetClient sets the http.Client to use when making requests.

type Feature

type Feature struct {
	// Key is the name of the Feature.
	Key string `json:"key"`
	// Value is the string value of this Feature.
	Value string `json:"value"`
	// Type is the type of the Feature.
	// Can be "number", "text", "keyword", "list", "image_url" or "image_base64"..
	Type string `json:"type"`
}

Feature represents a single feature, to describe an input or a choice for example age:28 or location:"London".

func FeatureImageBase64

func FeatureImageBase64(key string, data string) Feature

FeatureImageBase64 makes a Feature that is base 64 encoded.

func FeatureImageURL

func FeatureImageURL(key string, url string) Feature

FeatureImageURL makes a Feature that points to a hosted image.

func FeatureKeyword

func FeatureKeyword(key string, keyword string) Feature

FeatureKeyword makes a textual Feature that will not be tokenized. Use FeatureList to provide multiple keywords in a single Feature. Use Text for bodies of text that should be tokenized.

func FeatureList

func FeatureList(key string, keywords ...string) Feature

FeatureList makes a Feature made up of multiple keywords.

func FeatureNumber

func FeatureNumber(key string, value float64) Feature

FeatureNumber makes a numerical Feature.

func FeatureText

func FeatureText(key string, text string) Feature

FeatureText makes a textual Feature that will be tokenized. Use FeatureKeyword for values that should not be tokenized.

type Model

type Model struct {
	// ID is the ID of the model.
	ID string `json:"id,omitempty"`
	// Name is the human readable name of the Model.
	Name string `json:"name"`
	// Options are optional Model settings to adjust the behaviour
	// of this Model within Suggestionbox.
	Options *ModelOptions `json:"options,omitempty"`
	// Choices are the options this Model will select from.
	Choices []Choice `json:"choices,omitempty"`
}

Model represents a single model inside Suggestionbox.

func NewModel

func NewModel(id, name string, choices ...Choice) Model

NewModel makes a new Model.

type ModelOptions

type ModelOptions struct {
	// RewardExpirationSeconds is the number of seconds to wait for
	// the reward before it expires.
	RewardExpirationSeconds int `json:"reward_expiration_seconds,omitempty"`

	// Epsilon enables proportionate exploiting vs exploring ratio.
	Epsilon float64 `json:"epsilon,omitempty"`

	// SoftmaxLambda enables adaptive exploiting vs exploring ratio.
	SoftmaxLambda float64 `json:"softmax_lambda,omitempty"`

	// Ngrams describes the n-grams for text analysis.
	Ngrams int `json:"ngrams,omitempty"`
	// Skipgrams describes the skip-grams for the text analysis.
	Skipgrams int `json:"skipgrams,omitempty"`
}

ModelOptions describes the behaviours of a Model.

type ModelStats

type ModelStats struct {
	// Predictions is the number of predictions this model has made.
	Predictions int `json:"predictions"`
	// Rewards is the number of rewards the model has received.
	Rewards int `json:"rewards"`
	// RewardRatio is the ratio between Predictions and Rewards.
	RewardRatio float64 `json:"reward_ratio"`
	// Explores is the number of times the model has explored,
	// to learn new things.
	Explores int `json:"explores"`
	// Exploits is the number of times the model has exploited learning.
	Exploits int `json:"exploits"`
	// ExploreRatio is the ratio between exploring and exploiting.
	ExploreRatio float64 `json:"explore_ratio"`
}

ModelStats are the statistics for a Model.

type PredictRequest

type PredictRequest struct {
	// Inputs is a list of Feature objects that will be used when
	// making the prediction.
	Inputs []Feature `json:"inputs,omitempty"`
}

PredictRequest contains information about the prediction that Suggestionbox will make.

type PredictResponse

type PredictResponse struct {
	// Choices contains the predictions.
	Choices []Prediction `json:"choices,omitempty"`
}

PredictResponse contains prediction choices.

type Prediction

type Prediction struct {
	// ID is the choice identifier being predicted.
	ID string `json:"id,omitempty"`
	// RewardID is the ID of the reward that should be sent if this
	// prediction was successful.
	RewardID string `json:"reward_id,omitempty"`
	// Score is a numerical value indicating how this prediction relates
	// to other predictions.
	Score float64 `json:"score,omitempty"`
}

Prediction is a predicted choice.

type Reward

type Reward struct {
	// RewardID is the ID of the reward being reported.
	RewardID string `json:"reward_id"`
	// Value is the weight of the reward.
	// Usually 1.
	Value float64 `json:"value,omitempty"`
}

Reward is used to inform Suggestionbox of a successful prediction.