sdk

package module
v1.9.0 Latest Latest
Warning

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

Go to latest
Published: Aug 21, 2024 License: MIT Imports: 9 Imported by: 0

README

Rainbird SDK (Go)

Beautiful, automatically generated code documentation is available at https://pkg.go.dev/gitlab.com/rainbird-ai/sdk-go

For more information on the company, our unique reasoning engine, and the benefits of understandable, explainable AI please visit our corporate site at https://rainbird.ai

Usage

Create a client using your API key and pointing to the desired environment (commonly Community or Enterprise):

client := sdk.Client{
	APIKey:         os.Getenv("RB_API_KEY"),
	EnvironmentURL: sdk.EnvCommunity,
}

Use that client to create a session with a knowledge map by its ID. By passing a non empty contextID, the session will be connected to the context scope with that ID:

session, err := client.NewSession(kmID, contextID)

Query that session, and Rainbird will either ask you a question or give you answers:

question, answers, err := session.Query("John", "speaks", "")

Known issues

Rainbird's API documentation currently describes a response format for errors that the API doesn't adhere to. This SDK works around those limitations where possible.

The engine and supporting documentation currently used very mixed terminology. For reference, this SDK will be endeavouring to move terminology to be more in line with current accepted terminology.

  • The user makes a Query
  • The engine asks a Question
  • The user provides an Answer
  • The engine gives a Result

Documentation

Index

Constants

View Source
const (
	// EnvCommunity is the default engine URL
	EnvCommunity = "https://api.rainbird.ai"
	// EnvEnterprise is the URL used by premium Enterprise clients
	EnvEnterprise = "https://api-enterprise.rainbird.ai"
)
View Source
const NoContext string = ""

NoContext is the default way to interact with the engine; without defining a context in which to work

View Source
const Version = "0.7.0"

Version is the version of this SDK

Variables

View Source
var (
	// ErrClientMissingAPIKey is returned when an operation is attempted with a
	// client for which it requires an API key but has none
	ErrClientMissingAPIKey = errors.New("Client Missing API Key")
	// ErrClientMissingEnvironmentURL is returned when an operation is attempted
	// with a client for which it must contact an API, but no API URL has been
	// configured
	ErrClientMissingEnvironmentURL = errors.New("Client Missing Environment URL")
	// ErrNewSessionInvalidKMID is returned when a new session is being started,
	// but the KMID is invalid (for example, due to being empty like "")
	ErrNewSessionInvalidKMID = errors.New("NewSessionInvalidKMID")

	// ErrFactNotFound represents a fact not found error.
	ErrFactNotFound = errors.New("fact not found")
)
View Source
var (
	// ErrQueryBlankRelationship is given when relationship is "" in a query
	// A relationship must always be provided.
	ErrQueryBlankRelationship = errors.New("blank relationship")
)

Functions

func CertaintyFactor added in v1.0.0

func CertaintyFactor(cf string, cfPointer *int) int

CertaintyFactor returns the certainty factor from QAnswer or InjectFact

Types

type Answer

type Answer struct {
	Subject         string                `json:"subject,omitempty"`
	Object          interface{}           `json:"object,omitempty"`
	Certainty       uint64                `json:"certainty,omitempty"`
	FactID          string                `json:"factID,omitempty"`
	Relationship    string                `json:"relationship,omitempty"`
	SubjectMetadata map[string][]MetaData `json:"subjectMetadata,omitempty"`
	SubjectValue    interface{}           `json:"subjectValue,omitempty"`
	ObjectMetadata  map[string][]MetaData `json:"objectMetadata,omitempty"`
	ObjectValue     interface{}           `json:"objectValue,omitempty"`
}

Answer is data provided by the engine as a result/decision

func (*Answer) String

func (a *Answer) String() string

String makes *Answer satisfy fmt.Stringer

type Client

type Client struct {
	// APIKey is the user's authentication for the session. Required.
	APIKey string
	// EnvironmentURL is the URL of the API to use. This is most commonly
	// EnvCommunity. Required.
	EnvironmentURL string

	// HTTPClient allows the user to provide a client other than
	// http.DefaultClient with which to make network calls. Good for testing,
	// intercepting, or other advanced uses. Optional.
	HTTPClient *http.Client
}

Client is a grouped set of config for interacting with a Rainbird engine

func (*Client) Evidence added in v0.13.0

func (c *Client) Evidence(sessionID string, factID string, evidenceKey *string) (*Evidence, error)

Evidence returns Evidence for a given factID

func (*Client) HTTP added in v0.7.0

func (c *Client) HTTP() *http.Client

HTTP retrieves an appropriate client for making HTTP calls

func (*Client) Interactions added in v0.13.0

func (c *Client) Interactions(sessionID string, interactionKey *string) ([]InteractionEvent, error)

Interactions returns an array of time-stamped session events

func (*Client) KnowledgeMapVersion added in v0.13.0

func (c *Client) KnowledgeMapVersion(sessionID string) (*KnowledgeMap, error)

KnowledgeMapVersion returns information about the knowledge map for a session

func (*Client) NewSession

func (c *Client) NewSession(kmID string, contextID string, useDraft *bool, version *int) (*Session, error)

NewSession creates a new engine interaction session

func (*Client) ResumeSession

func (c *Client) ResumeSession(sessionID string) (*Session, error)

ResumeSession resumes a session from the given ID

func (*Client) SessionFacts added in v0.13.0

func (c *Client) SessionFacts(sessionID string) (*Facts, error)

SessionFacts returns facts from the given session

func (*Client) Version

func (c *Client) Version() (string, error)

Version contacts the engine API and retrieves its version information

type ConceptInstance added in v0.12.0

type ConceptInstance struct {
	Type     *string     `json:"type,omitempty"`
	Concept  *string     `json:"concept,omitempty"`
	Value    interface{} `json:"value,omitempty"`
	DataType string      `json:"dataType,omitempty"`
}

ConceptInstance is an instance of a knowledge map concept

func (*ConceptInstance) GetConcept added in v0.13.0

func (ci *ConceptInstance) GetConcept() string

GetConcept returns the name of the concept - sometimes refered to as the type

func (*ConceptInstance) String added in v0.12.0

func (ci *ConceptInstance) String() string

type ConditionExpression added in v0.12.0

type ConditionExpression struct {
	WasMet     bool       `json:"wasMet,omitempty"`
	Expression Expression `json:"expression,omitempty"`
	// contains filtered or unexported fields
}

ConditionExpression describes a condition created from an expression

func (ConditionExpression) Salience added in v0.12.0

func (ce ConditionExpression) Salience() int

Salience value of the given condition

func (ConditionExpression) Type added in v0.12.0

Type of ConditionType

type ConditionRelationship added in v0.12.0

type ConditionRelationship struct {
	Certainty    int         `json:"certainty,omitempty"`
	FactID       string      `json:"factID,omitempty"`
	FactKey      *string     `json:"factKey,omitempty"`
	Object       interface{} `json:"object,omitempty"`
	ObjectType   string      `json:"objectType,omitempty"`
	Relationship string      `json:"relationship,omitempty"`
	Subject      interface{} `json:"subject,omitempty"`
	// contains filtered or unexported fields
}

ConditionRelationship describes a condition created from a relationship

func (ConditionRelationship) Salience added in v0.12.0

func (cr ConditionRelationship) Salience() int

Salience value of the given condition

func (ConditionRelationship) Type added in v0.12.0

Type of ConditionType

type ConditionType added in v0.12.0

type ConditionType = int

ConditionType describes the various types of evidence conditions that can be returned

const (
	RelationshipType ConditionType = iota
	ExpressionType
)

All ConditionTypes

type Conditioner added in v0.12.0

type Conditioner interface {
	Type() ConditionType
	Salience() int
}

Conditioner is a common interface for the various ConditionTypes

type Datasource added in v0.11.0

type Datasource struct {
	Relationship string `json:"relationship,omitempty"`
	Certainty    int    `json:"certainty,omitempty"`
}

Datasource describes a datasource inject event

func (*Datasource) String added in v0.11.0

func (i *Datasource) String() string

String makes *interactionInject satisfy fmt.Stringer

type Event added in v0.11.0

type Event int

Event describes the various events that can be returned via the interactions endpoint

const (
	StartEvent Event = iota
	QuestionEvent
	AnswerEvent
	QueryEvent
	InjectEvent
	DatasourceEvent
	ResultEvent
)

All possible event types

func (Event) String added in v0.11.0

func (e Event) String() string

type Evidence added in v0.12.0

type Evidence struct {
	Fact Fact  `json:"fact,omitempty"`
	Rule *Rule `json:"rule,omitempty"`
	Time int   `json:"time,omitempty"`
}

Evidence is produced from the raw EvidenceResponse

func (*Evidence) String added in v0.12.0

func (e *Evidence) String() string

String makes *Evidence satisfy fmt.Stringer

type Expression added in v0.12.0

type Expression struct {
	Text string `json:"text,omitempty"`
}

Expression is the text representation of a knowledge map expression

type Fact added in v0.12.0

type Fact struct {
	ID           string          `json:"id,omitempty"`
	Source       string          `json:"source,omitempty"`
	Subject      ConceptInstance `json:"subject,omitempty"`
	Relationship string          `json:"relationship,omitempty"`
	Object       ConceptInstance `json:"object,omitempty"`
	Certainty    int             `json:"certainty,omitempty"`
}

Fact contains information that the engine knows from a session

func (*Fact) String added in v0.12.0

func (f *Fact) String() string

String makes *Fact satifsy fmt.Stringer

type Facts added in v0.13.0

type Facts struct {
	Global  []Fact `json:"global,omitempty"`
	Context []Fact `json:"context,omitempty"`
	Local   []Fact `json:"local,omitempty"`
}

Facts contains the three types of Fact a session can have

func (*Facts) Flatten added in v0.13.0

func (f *Facts) Flatten() []Fact

Flatten helper function that returns all facts in one slice

func (*Facts) String added in v0.13.0

func (f *Facts) String() string

String makes *Facts satisfy fmt.Stringer

type InjectFact

type InjectFact struct {
	Subject      string             `json:"subject"`
	Relationship string             `json:"relationship"`
	Object       interface{}        `json:"object"`
	Certainty    string             `json:"cf"`
	CertFactor   *int               `json:"certainty,omitempty"`
	Metadata     InjectFactMetadata `json:"metadata"`
}

InjectFact is the structure of facts to add to a session via the Inject call

func (*InjectFact) CertaintyFactor added in v0.11.0

func (i *InjectFact) CertaintyFactor() int

func (*InjectFact) String added in v0.11.0

func (i *InjectFact) String() string

String makes *InjectFact satisfy fmt.Stringer

type InjectFactMetadata added in v1.4.0

type InjectFactMetadata struct {
	Source InjectFactSource `json:"source,omitempty"`
}

InjectFactMetadata holds metadata about an injected fact

type InjectFactSource added in v1.4.0

type InjectFactSource string

InjectFactSource indicates the source of an injected fact

const (
	// InjectFactSourceSystem indicates that the fact originates from another system (default)
	InjectFactSourceSystem InjectFactSource = "system"
	// InjectFactSourceUser indicates that the fact originates from a user or human in the loop
	InjectFactSourceUser InjectFactSource = "user"
)

type InteractionEvent added in v0.11.0

type InteractionEvent struct {
	Event   Event       `json:"event"`
	Created time.Time   `json:"created"`
	Data    interface{} `json:"data"`
}

InteractionEvent describes an event entry in the interactions log

func InteractionEvents added in v0.11.0

func InteractionEvents(response []InteractionResponse) ([]InteractionEvent, error)

InteractionEvents converts the api response to interactionEvent domain objects

type InteractionResponse added in v0.11.0

type InteractionResponse struct {
	Event   string          `json:"event"`
	Values  json.RawMessage `json:"values"`
	Created string          `json:"created"`
}

InteractionResponse is the raw response from the api

type KnowledgeMap added in v0.13.0

type KnowledgeMap struct {
	ID             string     `json:"id,omitempty"`
	Name           string     `json:"name,omitempty"`
	VersionID      string     `json:"versionID,omitempty"`
	VersionNumber  *int       `json:"versionNumber,omitempty"`
	VersionCreated *time.Time `json:"versionCreated,omitempty"`
	VersionStatus  string     `json:"versionStatus,omitempty"`
}

KnowledgeMap represents the knowledge map version information returned from the session endpoint

func (*KnowledgeMap) String added in v0.13.0

func (s *KnowledgeMap) String() string

String makes *Evidence satisfy fmt.Stringer

type KnownAnswer added in v0.5.1

type KnownAnswer struct {
	CF           float64     `json:"cf,omitempty"`
	Object       interface{} `json:"object,omitempty"`
	Relationship struct {
		AllowCertainty     bool          `json:"allowCertainty,omitempty"`
		AllowCF            bool          `json:"allowCF,omitempty"`
		AllowUnknown       bool          `json:"allowUnknown,omitempty"`
		Askable            string        `json:"askable,omitempty"`
		CanAdd             string        `json:"canAdd,omitempty"`
		CanAddAttr         string        `json:"canAdd_attr,omitempty"`
		FSID               uint64        `json:"fsid,omitempty"`
		Metadata           interface{}   `json:"metadata,omitempty"`
		Name               string        `json:"name,omitempty"`
		Object             string        `json:"object,omitempty"`
		ObjectType         string        `json:"objectType,omitempty"`
		Plural             bool          `json:"plural,omitempty"`
		SubjectDatasources []interface{} `json:"subjectDatasources,omitempty"`
		SubjectType        string        `json:"subjectType,omitempty"`
		Questions          struct {
			EN struct {
				SecondFormSubject string `json:"secondFormSubject,omitempty"`
			} `json:"en,omitempty"`
		} `json:"questions,omitempty"`
		Subject string `json:"subject,omitempty"`
	} `json:"relationship,omitempty"`
	Subject string `json:"subject,omitempty"`
}

KnownAnswer is a hint provided by the engine for information it already knows

type MetaData

type MetaData struct {
	Data     string
	DataType string
}

MetaData is a collection of additional information about Concepts

type QAnswer added in v0.6.0

type QAnswer struct {
	Subject      string      `json:"subject"`
	Relationship string      `json:"relationship"`
	Object       interface{} `json:"object"`
	CF           string      `json:"cf"`
	Certainty    *int        `json:"certainty,omitempty"`
	Answer       string      `json:"answer,omitempty"`
	Unanswered   bool        `json:"unanswered,omitempty"`
}

QAnswer is a user's answer to an Question from the engine

func (*QAnswer) CertaintyFactor added in v0.11.0

func (q *QAnswer) CertaintyFactor() int

func (*QAnswer) String added in v0.11.0

func (q *QAnswer) String() string

String makes *QAnswer satisfy fmt.Stringer

type Query added in v0.11.0

type Query struct {
	Subject      *string `json:"subject,omitempty"`
	Relationship string  `json:"relationship,omitempty"`
	Object       *string `json:"object,omitempty"`
}

Query describes a user made query to the engine

func (*Query) String added in v0.11.0

func (q *Query) String() string

String makes *query satisfy fmt.Stringer

type QueryOption added in v1.6.0

type QueryOption func(o queryOption) queryOption

QueryOption add optional parameter to sdk query endpoint

func AddHeaders added in v1.6.0

func AddHeaders(headers http.Header) QueryOption

AddHeaders assigns the headers to the queryOption struct

type Question

type Question struct {
	AllowCF        bool                  `json:"allowCF,omitempty"`
	AllowUnknown   bool                  `json:"allowUnknown,omitempty"`
	CanAdd         bool                  `json:"canAdd,omitempty"`
	Concepts       []QuestionConcept     `json:"concepts,omitempty"`
	DataType       string                `json:"dataType,omitempty"`
	KnownAnswers   []KnownAnswer         `json:"knownAnswers,omitempty"`
	Object         interface{}           `json:"object,omitempty"`
	ObjectMetadata map[string][]MetaData `json:"objectMetadata,omitempty"`
	ObjectType     string                `json:"objectType,omitempty"`
	Plural         bool                  `json:"plural,omitempty"`
	Prompt         string                `json:"prompt,omitempty"`
	Relationship   string                `json:"relationship,omitempty"`
	Subject        string                `json:"subject,omitempty"`
	Type           string                `json:"type,omitempty"`
}

Question is the structure of a request from the engine when asking for more information from the user

func (*Question) String

func (q *Question) String() string

String makes *Question satisfy fmt.Stringer

type QuestionConcept

type QuestionConcept struct {
	ConceptType     string      `json:"conceptType,omitempty"`
	Name            interface{} `json:"name,omitempty"`
	Type            string      `json:"type,omitempty"`
	Value           interface{} `json:"value,omitempty"`
	InvalidResponse bool        `json:"invalidResponse,omitempty"`
	FSID            uint64      `json:"fsid,omitempty"`
}

QuestionConcept is how the engine expressed concepts when asking a Question

type Relationship added in v0.5.1

type Relationship struct {
	Type string `json:"type,omitempty"`
}

Relationship connects concepts in a knowledge map

type Rule added in v0.12.0

type Rule struct {
	Bindings   map[string]interface{}
	Conditions []Conditioner
}

Rule describes the conditions upon which a fact was produced

type Session

type Session struct {
	ID string
	// contains filtered or unexported fields
}

Session is a started engine interaction with a knowledge map

func (*Session) Inject

func (s *Session) Inject(facts []InjectFact) error

Inject adds facts to a running session

func (*Session) Query

func (s *Session) Query(sub, rel string, obj interface{}, optionConstructors ...QueryOption) ([]Question, []Answer, error)

Query is the first interaction with a session, setting a goal. Leaving sub, obj and/or both blank ("") will instruct the engine in what you wish to find out. For example, s.Query("John", "speaks", "") will instruct the engine that you wish to find out which languages John speaks.

func (*Session) Response

func (s *Session) Response(answers []QAnswer) ([]Question, []Answer, error)

Response submits a user response to the engine, and must be a response to a Question the engine has asked.

func (*Session) Undo

func (s *Session) Undo() ([]Question, []Answer, error)

Undo steps the engine back in the case of a mistake, for example if a Response has been given in error.

type Start added in v0.11.0

type Start struct {
	SessionID   string `json:"sessionID"`
	UseDraft    bool   `json:"useDraft"`
	KmVersionID string `json:"kmVersionID"`
}

Start represents the start of a Rainbird session

func (*Start) String added in v0.11.0

func (s *Start) String() string

String makes *Start satisfy fmt.Stringer

Directories

Path Synopsis
cmd
rb

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL