inferable

README

Go SDK for Inferable

Inferable Go Client is a Go package that provides a client for interacting with the Inferable API. It allows you to register your go functions against the Inferable control plane and create powerful LLM-powered workflows with structured outputs, agents, and tools.

Installation

To install the Inferable Go Client, use the following command:

go get github.com/inferablehq/inferable/sdk-go

Quick Start

Initializing Inferable

To create a new Inferable client, use the New function:

import "github.com/inferablehq/inferable/sdk-go/inferable"

client, err := inferable.New("your-api-secret", "https://api.inferable.ai")

if err != nil {
    // Handle error
}

If you don't provide an API key or base URL, it will attempt to read them from the following environment variables:

• INFERABLE_API_SECRET
• INFERABLE_API_ENDPOINT

Registering a Function

Register a "SayHello" function with the control-plane.

type MyInput struct {
    Message string `json:"message"`
}

err := client.Tools.Register(inferable.Tool{
    Func:        myFunc,
    Name:        "SayHello",
    Description: "A simple greeting function",
})

if err != nil {
    // Handle error
}

Creating a Workflow

Workflows are a way to define a sequence of actions to be executed. They run on your own compute and can be triggered from anywhere via the API.

import (
    "fmt"
    "github.com/inferablehq/inferable/sdk-go/inferable"
)

// Create a workflow
workflow := client.Workflows.Create(inferable.WorkflowConfig{
    Name: "simple-workflow",
    InputSchema: struct {
        ExecutionId string `json:"executionId"`
        Text        string `json:"text"`
    }{},
})

// Define the workflow handler
workflow.Version(1).Define(func(ctx inferable.WorkflowContext, input struct {
    ExecutionId string `json:"executionId"`
    Text        string `json:"text"`
}) (interface{}, error) {
    // Log a message
    ctx.Log("info", map[string]interface{}{
        "message": "Starting workflow",
    })

    // Use the LLM to generate structured output
    result, err := ctx.LLM.Structured(inferable.StructuredInput{
        Input: input.Text,
        Schema: struct {
            Summary string `json:"summary"`
            Topics  []string `json:"topics"`
        }{},
    })

    if err != nil {
        return nil, err
    }

    return result, nil
})

// Start listening for workflow executions
err = workflow.Listen()
if err != nil {
    // Handle error
}
defer workflow.Unlisten()

Triggering a Workflow

You can trigger a workflow from your application code:

executionId := "unique-execution-id"

err = client.Workflows.Trigger("simple-workflow", executionId, map[string]interface{}{
    "text": "Inferable is a platform for building LLM-powered applications.",
})
if err != nil {
    // Handle error
}

Agents and Tool Use

You can define tools and agents that can be used within your workflows. For more information on tools and agents, see the Inferable documentation.

Adding Tools to Workflows

You can register tools that can be used within your workflows:

// Register a tool for the workflow
workflow.Tools.Register(inferable.WorkflowTool{
    Name: "searchDatabase",
    InputSchema: struct {
        SearchQuery string `json:"searchQuery"`
    }{},
    Func: func(input struct {
        SearchQuery string `json:"searchQuery"`
    }, ctx inferable.ContextInput) (struct {
        Result string `json:"result"`
    }, error) {
        // Implement your tool logic here
        result := struct {
            Result string `json:"result"`
        }{
            Result: "Found data for: " + input.SearchQuery,
        }
        return result, nil
    },
})

Using Agents in Workflows

Agents are autonomous LLM-based reasoning engines that can use tools to achieve pre-defined goals:

// Use the agent to search
result, interrupt, err := ctx.Agents.React(inferable.ReactAgentConfig{
    Name: "search",
    Instructions: inferable.Helpers.StructuredPrompt(struct {
        Facts []string
        Goals []string
    }{
        Facts: []string{"You are a search assistant"},
        Goals: []string{"Find information based on the user's query"},
    }),
    Schema: struct {
        Result string `json:"result"`
    }{},
    Tools: []string{"searchDatabase"},
    Input: "What information can you find about machine learning?",
})

if err != nil {
    // Handle error
}

if interrupt != nil {
    // Handle interrupt (e.g., human-in-the-loop)
    return interrupt, nil
}

// Process the agent result
fmt.Printf("Agent result: %v\n", result)

IMPORTANT: The ctx.Agents.React will return an interrupt if the workflow needs to pause and resume. Therefore, you should return the interrupt as the result of the workflow handler, when present.

if interrupt != nil {
    return interrupt, nil
}

Caching Results with Memo

You can cache expensive operations using the Memo function to avoid redundant computations:

// Cache a result with a unique key
cachedResult, err := ctx.Memo("unique-cache-key", func() (interface{}, error) {
    // This expensive operation will only be executed once for the given key
    // Subsequent calls with the same key will return the cached result
    return map[string]interface{}{
        "data": "Expensive computation result",
    }, nil
})

if err != nil {
    // Handle error
}

// Use the cached result
fmt.Printf("Cached result: %v\n", cachedResult)

Logging and Observability

The Inferable Go Client provides a ctx.Log function that can be used to log messages and errors:

// Log a message
ctx.Log("info", map[string]interface{}{
    "message": "Starting workflow",
})

👉 The Golang SDK for Inferable reflects the types from the input struct of the function.

Unlike the NodeJs SDK, the Golang SDK for Inferable reflects the types from the input struct of the function. It uses the invopop/jsonschema library under the hood to generate JSON schemas from Go types through reflection.

If the input struct defines jsonschema properties using struct tags, the SDK will use those in the generated schema. This allows for fine-grained control over the schema generation.

Here's an example to illustrate this:

import (
    "github.com/inferablehq/inferable/sdk-go/inferable"
    "time"
)

type UserInput struct {
    ID        int       `json:"id" jsonschema:"required"`
    Name      string    `json:"name" jsonschema:"minLength=2,maxLength=50"`
    Email     string    `json:"email" jsonschema:"format=email"`
    BirthDate time.Time `json:"birth_date" jsonschema:"format=date"`
    Tags      []string  `json:"tags" jsonschema:"uniqueItems=true"`
}

func createUser(input UserInput, ctx inferable.ContextInput) string {
    // Function implementation
}


err := client.Tools.Register(inferable.Tool{
    Func:        createUser,
    Name:        "CreateUser",
    Description: "Creates a new user",
})

if err != nil {
    // Handle error
}

In this example, the UserInput struct uses jsonschema tags to define additional properties for the schema:

• The id field is marked as required.
• The name field has minimum and maximum length constraints.
• The email field is specified to be in email format.
• The birth_date field is set to date format.
• The tags field is defined as an array with unique items.

When this function is registered, the Inferable Go SDK will use these jsonschema tags to generate a more detailed and constrained JSON schema for the input.

The invopop/jsonschema library provides many more options for schema customization, including support for enums, pattern validation, numeric ranges, and more.

Documentation

• Inferable documentation contains all the information you need to get started with Inferable.

Support

For support or questions, please create an issue in the repository.

Contributing

Contributions to the Inferable Go Client are welcome. Please ensure that your code adheres to the existing style and includes appropriate tests.

Documentation

Overview

Package inferable provides a client for interacting with the Inferable API.

Index

• Constants
• Variables
• type Agent
  • func (a *Agent) SendMessage(message string) error
• type Agents
  • func (a *Agents) React(config ReactAgentConfig) (interface{}, *Interrupt, error)
• type ContextInput
• type HandleCustomAuthInput
• type Inferable
  • func New(options InferableOptions) (*Inferable, error)
• type InferableOptions
• type Interrupt
  • func ApprovalInterrupt(message string) *Interrupt
  • func GeneralInterrupt(message string) *Interrupt
  • func NewInterrupt(typ VALID_INTERRUPT_TYPES, message string) *Interrupt
  • func (i *Interrupt) Error() string
• type LLM
  • func (l *LLM) Structured(input StructuredInput) (interface{}, error)
• type Logger
• type OnStatusChangeInput
• type ReactAgentConfig
• type StructuredInput
• type Tool
• type VALID_INTERRUPT_TYPES
• type Workflow
  • func (w *Workflow) Listen() error
  • func (w *Workflow) Unlisten() error
  • func (w *Workflow) Version(version int) *WorkflowVersionBuilder
• type WorkflowConfig
• type WorkflowContext
• type WorkflowInput
• type WorkflowTool
• type WorkflowTools
  • func (t *WorkflowTools) Register(tool WorkflowTool)
• type WorkflowVersionBuilder
  • func (b *WorkflowVersionBuilder) Define(handler interface{})
• type Workflows
  • func (w *Workflows) Create(config WorkflowConfig) *Workflow
  • func (w *Workflows) Trigger(workflowName string, executionId string, input interface{}) error

Constants

const (
	MaxConsecutivePollFailures = 50
	DefaultRetryAfter          = 10
)

const (
	// DefaultAPIEndpoint is the default endpoint for the Inferable API.
	DefaultAPIEndpoint = "https://api.inferable.ai"
)

const Version = "0.1.44"

Version of the inferable package

Variables

var Helpers = struct {
	// StructuredPrompt creates a structured prompt with facts and goals
	StructuredPrompt func(params struct {
		Facts []string
		Goals []string
	}) string
}{
	StructuredPrompt: func(params struct {
		Facts []string
		Goals []string
	}) string {
		result := "# Facts\n"
		for _, fact := range params.Facts {
			result += "- " + fact + "\n"
		}
		result += "# Your goals\n"
		for _, goal := range params.Goals {
			result += "- GOAL: " + goal + "\n"
		}
		return result
	},
}

Helpers provides helper functions for workflows

Types

type Agent

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

Agent represents an AI agent that can interact with users and perform tasks. It provides methods for sending messages and receiving responses.

func (*Agent) SendMessage

func (a *Agent) SendMessage(message string) error

SendMessage sends a message to the agent and waits for a response. It enables bidirectional communication with the agent.

type Agents

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

Agents provides functionality for creating and managing AI agents within workflows. It enables workflows to create agents that can perform tasks and interact with users.

func (*Agents) React

func (a *Agents) React(config ReactAgentConfig) (interface{}, *Interrupt, error)

React creates a React agent with the provided configuration. It initializes the agent and returns its result along with any interrupts. If interrupt is not nil, you must return it as the result of the workflow handler.

result, interrupt, err := ctx.Agents.React(ReactAgentConfig{
	Name: "my-agent",
	Instructions: "You are a helpful assistant",
	Input: "Hello, how are you?",
	Schema: struct {
		Result string `json:"result"`
	}{},
})

if err != nil {
	// Handle error
}

if interrupt != nil {
  return interrupt, nil
}

return result, nil

type ContextInput

type ContextInput struct {
	AuthContext interface{} `json:"authContext,omitempty"`
	RunContext  interface{} `json:"runContext,omitempty"`
	Approved    bool        `json:"approved"`
}

type HandleCustomAuthInput

type HandleCustomAuthInput struct {
	Token string `json:"token"`
}

Input object for handleCustomAuth functions https://docs.inferable.ai/pages/custom-auth

type Inferable

type Inferable struct {

	// Tools provides access to tool registration and management.
	Tools *pollingAgent
	// Workflows provides access to workflow creation and management.
	Workflows *Workflows
	// contains filtered or unexported fields
}

Inferable is the main client for interacting with the Inferable platform. It provides access to tools, workflows, and other Inferable services. Use the New function to create a new instance of Inferable.

func New

func New(options InferableOptions) (*Inferable, error)

type InferableOptions

type InferableOptions struct {
	APIEndpoint string
	APISecret   string
	MachineID   string
}

type Interrupt

type Interrupt struct {
	// Type specifies the kind of interrupt.
	Type VALID_INTERRUPT_TYPES `json:"type"`
	// Message provides additional context about the interrupt.
	Message string `json:"message,omitempty"`
}

Interrupt represents an interruption in the normal flow of a workflow execution. Interrupts can be used to pause execution for approval or to handle exceptional conditions.

func ApprovalInterrupt

func ApprovalInterrupt(message string) *Interrupt

ApprovalInterrupt creates a new approval interrupt with the specified message. Approval interrupts are used when user approval is required to continue execution.

func GeneralInterrupt

func GeneralInterrupt(message string) *Interrupt

GeneralInterrupt creates a new general interrupt with the specified message. General interrupts can be used for various purposes that require interrupting workflow execution.

func NewInterrupt

func NewInterrupt(typ VALID_INTERRUPT_TYPES, message string) *Interrupt

NewInterrupt creates a new Interrupt with the specified type and message. This is a general constructor for creating interrupts.

func (*Interrupt) Error

func (i *Interrupt) Error() string

Error implements the error interface, allowing Interrupts to be used as errors. This enables interrupts to be returned from functions that return errors.

type LLM

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

LLM provides LLM (Large Language Model) functionality for workflows. It enables workflows to interact with language models for text generation and processing.

func (*LLM) Structured

func (l *LLM) Structured(input StructuredInput) (interface{}, error)

Structured generates structured output from the LLM based on the provided input. It sends the input to the LLM and returns the structured response according to the schema.

result, err := ctx.LLM.Structured(StructuredInput{
	Input: "Hello, how are you?",
	Schema: struct {
		Result string `json:"result"`
	}{},
})

if err != nil {
	// Handle error
}

return result, nil

type Logger

type Logger interface {
	// Info logs an informational message with associated metadata.
	Info(message string, meta map[string]interface{})
	// Error logs an error message with associated metadata.
	Error(message string, meta map[string]interface{})
}

Logger interface for workflow logging. Implementations of this interface can be used to log workflow events.

type OnStatusChangeInput

type OnStatusChangeInput struct {
	Status string      `json:"status"`
	RunId  string      `json:"runId"`
	Result interface{} `json:"result"`
	Tags   interface{} `json:"tags"`
}

Input object for onStatusChange functions https://docs.inferable.ai/pages/runs#onstatuschange

type ReactAgentConfig

type ReactAgentConfig struct {
	// Name of the agent
	Name string
	// Instructions for the agent
	Instructions string
	// Input for the agent
	Input string
	// Schema for the agent result
	Schema interface{}
	// Tools for the agent
	Tools []string
}

ReactAgentConfig holds the configuration for a React agent. It defines the agent's name, instructions, input, schema, and available tools.

type StructuredInput

type StructuredInput struct {
	// Input is the text prompt for the LLM.
	Input string `json:"input"`
	// Schema defines the expected structure of the LLM output.
	Schema interface{} `json:"schema"`
}

StructuredInput represents input for structured LLM generation. It includes the input text and a schema defining the expected output structure.

type Tool

type Tool struct {
	Name        string
	Description string

	Config interface{}
	Func   interface{}
	// contains filtered or unexported fields
}

type VALID_INTERRUPT_TYPES

type VALID_INTERRUPT_TYPES string

VALID_INTERRUPT_TYPES defines the valid types of interrupts that can occur during workflow execution.

const (
	// APPROVAL indicates an interrupt that requires user approval to continue.
	APPROVAL VALID_INTERRUPT_TYPES = "approval"
	// GENERAL indicates a general interrupt that can be used for various purposes.
	GENERAL VALID_INTERRUPT_TYPES = "general"
)

type Workflow

type Workflow struct {
	Tools *WorkflowTools
	// contains filtered or unexported fields
}

Workflow represents a workflow in the Inferable system. It contains the workflow's configuration, handlers, and tools.

func (*Workflow) Listen

func (w *Workflow) Listen() error

Listen starts listening for workflow executions. It registers the workflow and its tools with the Inferable service and begins processing incoming workflow execution requests.

func (*Workflow) Unlisten

func (w *Workflow) Unlisten() error

Unlisten stops listening for workflow executions. It unregisters the workflow from the Inferable service and stops processing incoming workflow execution requests.

func (*Workflow) Version

func (w *Workflow) Version(version int) *WorkflowVersionBuilder

Version sets the version for the workflow. It returns a WorkflowVersionBuilder that can be used to define the handler for this version.

type WorkflowConfig

type WorkflowConfig struct {
	// Name is the unique identifier for the workflow.
	Name string
	// Description provides a human-readable explanation of the workflow's purpose.
	Description string
	// InputSchema defines the expected structure of the workflow input.
	InputSchema interface{}
	// Logger is used for logging workflow events.
	Logger Logger
}

WorkflowConfig holds the configuration for a workflow. It defines the workflow's name, description, input schema, and logger.

type WorkflowContext

type WorkflowContext struct {
	// Input for the workflow
	Input interface{}
	// Approved indicates if the workflow is approved
	Approved bool
	// LLM functionality for the workflow
	LLM *LLM
	// Memo caches results for the workflow. It provides a way to store and retrieve
	// computation results across workflow executions. The function takes a name to
	// identify the cached result and a function that computes the result if not cached.
	// If a result with the given name exists in the cache, it is returned without
	// executing the function. Otherwise, the function is executed and its result is
	// stored in the cache before being returned.
	Memo func(name string, fn func() (interface{}, error)) (interface{}, error)
	// Log logs information for the workflow. It records a status message and associated
	// metadata for the current workflow execution. This information can be used for
	// monitoring, debugging, and auditing workflow executions. The status parameter
	// indicates the current state or event being logged, and the meta parameter provides
	// additional context or data related to the status.
	Log func(status string, meta map[string]interface{}) error
	// Agents provides agent functionality for the workflow
	Agents *Agents
}

WorkflowContext provides context for workflow execution. It contains all the necessary information and functionality for a workflow to execute.

type WorkflowInput

type WorkflowInput struct {
	ExecutionID string `json:"executionId"`
}

WorkflowInput is the base input type for all workflows. It contains the execution ID which uniquely identifies a workflow execution.

type WorkflowTool

type WorkflowTool struct {
	// Name is the unique identifier for the tool.
	Name string
	// Description provides a human-readable explanation of the tool's purpose.
	Description string
	// InputSchema defines the expected structure of the tool input.
	InputSchema interface{}
	// Func is the function that implements the tool's functionality.
	Func interface{}
	// Config provides additional configuration for the tool.
	Config interface{}
}

WorkflowTool represents a tool that can be used within a workflow. Tools provide additional functionality that can be invoked during workflow execution.

type WorkflowTools

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

WorkflowTools provides tool registration functionality for workflows. It allows registering custom tools that can be used within a workflow.

func (*WorkflowTools) Register

func (t *WorkflowTools) Register(tool WorkflowTool)

Register registers a tool for the workflow. The tool will be available for use within the workflow execution.

type WorkflowVersionBuilder

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

WorkflowVersionBuilder builds a workflow version. It provides methods for defining the handler for a specific workflow version.

func (*WorkflowVersionBuilder) Define

func (b *WorkflowVersionBuilder) Define(handler interface{})

Define defines the handler for the workflow version. The handler is a function that will be called when the workflow is executed.

type Workflows

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

Workflows provides workflow management functionality. It allows creating and triggering workflows.

func (*Workflows) Create

func (w *Workflows) Create(config WorkflowConfig) *Workflow

Create creates a new workflow with the provided configuration. It initializes the workflow with the given name, description, input schema, and logger. Returns a new Workflow instance that can be further configured.

func (*Workflows) Trigger

func (w *Workflows) Trigger(workflowName string, executionId string, input interface{}) error

Trigger triggers a workflow execution with the provided input. It sends a request to the Inferable service to start a new execution of the specified workflow. The executionId uniquely identifies this execution instance.