nebo

package module
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Feb 12, 2026 License: MIT Imports: 10 Imported by: 0

README

Nebo Go SDK

Official Go SDK for building Nebo apps.

Install

go get github.com/nebolabs/nebo-sdk-go

Quick Start

package main

import (
    "context"
    "encoding/json"
    "fmt"
    "log"

    nebo "github.com/nebolabs/nebo-sdk-go"
)

type Calculator struct{}

func (c *Calculator) Name() string        { return "calculator" }
func (c *Calculator) Description() string { return "Performs arithmetic calculations." }

func (c *Calculator) Schema() json.RawMessage {
    return nebo.NewSchema("add", "subtract", "multiply", "divide").
        Number("a", "First operand", true).
        Number("b", "Second operand", true).
        Build()
}

func (c *Calculator) Execute(_ context.Context, input json.RawMessage) (string, error) {
    var in struct {
        Action string  `json:"action"`
        A      float64 `json:"a"`
        B      float64 `json:"b"`
    }
    if err := json.Unmarshal(input, &in); err != nil {
        return "", fmt.Errorf("invalid input: %w", err)
    }

    switch in.Action {
    case "add":
        return fmt.Sprintf("%g", in.A+in.B), nil
    case "subtract":
        return fmt.Sprintf("%g", in.A-in.B), nil
    case "multiply":
        return fmt.Sprintf("%g", in.A*in.B), nil
    case "divide":
        if in.B == 0 {
            return "", fmt.Errorf("division by zero")
        }
        return fmt.Sprintf("%g", in.A/in.B), nil
    default:
        return "", fmt.Errorf("unknown action: %s", in.Action)
    }
}

func main() {
    app, err := nebo.New()
    if err != nil {
        log.Fatal(err)
    }
    app.RegisterTool(&Calculator{})
    log.Fatal(app.Run())
}

Handler Interfaces

Capability Interface Manifest provides
Tool ToolHandler tool:<name>
Channel ChannelHandler channel:<name>
Gateway GatewayHandler gateway
UI UIHandler ui
Comm CommHandler comm
Schedule ScheduleHandler schedule

Schema Builder

Build JSON Schema for STRAP-pattern tool inputs:

schema := nebo.NewSchema("list", "create", "delete").
    String("name", "Resource name", true).
    Number("limit", "Max results", false).
    Bool("verbose", "Show details", false).
    Enum("format", "Output format", false, "json", "text").
    Build()

View Builder

Build structured UI views:

view := nebo.NewView("dashboard", "My Dashboard").
    Heading("title", "Status", "h2").
    Text("info", "All systems operational").
    Button("refresh", "Refresh", "primary").
    Divider("sep").
    Input("search", "", "Search...").
    Build()

Documentation

See Creating Nebo Apps for the full guide.

Documentation

Overview

Package nebo provides the SDK for building Nebo apps.

A Nebo app is a compiled binary that communicates with Nebo over gRPC via Unix sockets. The SDK handles all gRPC server setup, signal handling, and protocol bridging — you just implement handler interfaces for the capabilities your app provides.

Quick start: 

app, _ := nebo.New()
app.RegisterTool(&MyTool{})
log.Fatal(app.Run())

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrNoSockPath is returned when NEBO_APP_SOCK is not set.
	ErrNoSockPath = errors.New("NEBO_APP_SOCK environment variable is not set")

	// ErrNoHandlers is returned when Run() is called with no registered handlers.
	ErrNoHandlers = errors.New("no capability handlers registered — register at least one handler before calling Run()")
)

Functions

This section is empty.

Types

type App 

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

App is the main entry point for a Nebo app. It manages the gRPC server, capability registration, and lifecycle.

func New 

func New() (*App, error)

New creates a new Nebo App. It reads NEBO_APP_* environment variables and prepares the gRPC server. Returns ErrNoSockPath if NEBO_APP_SOCK is not set.

func (*App) Env 

func (a *App) Env() *AppEnv

Env returns the app's environment variables.

func (*App) OnConfigure 

func (a *App) OnConfigure(fn func(map[string]string))

OnConfigure sets a callback that is called when Nebo pushes settings updates. This is shared across all capability handlers.

func (*App) RegisterChannel 

func (a *App) RegisterChannel(h ChannelHandler)

RegisterChannel registers a ChannelHandler capability.

func (*App) RegisterComm 

func (a *App) RegisterComm(h CommHandler)

RegisterComm registers a CommHandler capability.

func (*App) RegisterGateway 

func (a *App) RegisterGateway(h GatewayHandler)

RegisterGateway registers a GatewayHandler capability.

func (*App) RegisterSchedule 

func (a *App) RegisterSchedule(h ScheduleHandler)

RegisterSchedule registers a ScheduleHandler capability.

func (*App) RegisterTool 

func (a *App) RegisterTool(h ToolHandler)

RegisterTool registers a ToolHandler capability.

func (*App) RegisterUI 

func (a *App) RegisterUI(h UIHandler)

RegisterUI registers a UIHandler capability.

func (*App) Run 

func (a *App) Run() error

Run starts the gRPC server on the Unix socket and blocks until SIGTERM/SIGINT. It removes any stale socket file before listening.

type AppEnv 

type AppEnv struct {
	Dir      string // NEBO_APP_DIR — app's installation directory
	SockPath string // NEBO_APP_SOCK — Unix socket path to listen on
	ID       string // NEBO_APP_ID — app ID from manifest
	Name     string // NEBO_APP_NAME — app name from manifest
	Version  string // NEBO_APP_VERSION — app version from manifest
	DataDir  string // NEBO_APP_DATA — path to app's data/ directory
}

AppEnv provides typed access to NEBO_APP_* environment variables. These are set by Nebo's sandbox when launching your app.

type ChannelHandler 

type ChannelHandler interface {
	ID() string
	Connect(ctx context.Context, config map[string]string) error
	Disconnect(ctx context.Context) error
	Send(ctx context.Context, channelID, text string) error
	Receive(ctx context.Context) (<-chan InboundMessage, error)
}

ChannelHandler is the interface for channel capability apps. Implement this to bridge an external messaging platform to Nebo.

type CommHandler 

type CommHandler interface {
	Name() string
	Version() string
	Connect(ctx context.Context, config map[string]string) error
	Disconnect(ctx context.Context) error
	IsConnected() bool
	Send(ctx context.Context, msg CommMessage) error
	Subscribe(ctx context.Context, topic string) error
	Unsubscribe(ctx context.Context, topic string) error
	Register(ctx context.Context, agentID string, capabilities []string) error
	Deregister(ctx context.Context) error
	Receive(ctx context.Context) (<-chan CommMessage, error)
}

CommHandler is the interface for comm capability apps. Implement this to provide inter-agent communication for Nebo.

type CommMessage 

type CommMessage struct {
	ID             string
	From           string
	To             string
	Topic          string
	ConversationID string
	Type           string // "message", "mention", "proposal", "command", "info", "task"
	Content        string
	Metadata       map[string]string
	Timestamp      int64
	HumanInjected  bool
	HumanID        string
}

CommMessage represents an inter-agent communication message.

type GatewayEvent 

type GatewayEvent struct {
	Type      string // "text", "tool_call", "thinking", "error", "done"
	Content   string
	Model     string
	RequestID string
}

GatewayEvent is a streamed event sent back to Nebo.

type GatewayHandler 

type GatewayHandler interface {
	Stream(ctx context.Context, req *GatewayRequest) (<-chan GatewayEvent, error)
	Cancel(ctx context.Context, requestID string) error
}

GatewayHandler is the interface for gateway capability apps. Implement this to provide LLM model routing to Nebo.

type GatewayMessage 

type GatewayMessage struct {
	Role       string
	Content    string
	ToolCallID string
	ToolCalls  string // JSON-encoded array
}

GatewayMessage is a single message in a conversation.

type GatewayRequest 

type GatewayRequest struct {
	RequestID   string
	Messages    []GatewayMessage
	Tools       []GatewayToolDef
	MaxTokens   int32
	Temperature float64
	System      string
	UserID      string
	UserPlan    string
	UserToken   string // Only populated if app has "user:token" permission
}

GatewayRequest represents an LLM chat completion request from Nebo.

type GatewayToolDef 

type GatewayToolDef struct {
	Name        string
	Description string
	InputSchema []byte // JSON Schema
}

GatewayToolDef describes a tool available to the model.

type InboundMessage 

type InboundMessage struct {
	ChannelID string
	UserID    string
	Text      string
	Metadata  string // JSON-encoded
}

InboundMessage represents a message received from an external platform.

type Schedule 

type Schedule = pb.Schedule

Schedule represents a single scheduled task.

type ScheduleHandler 

type ScheduleHandler interface {
	Create(ctx context.Context, req *pb.CreateScheduleRequest) (*pb.Schedule, error)
	Get(ctx context.Context, name string) (*pb.Schedule, error)
	List(ctx context.Context, limit, offset int32, enabledOnly bool) ([]*pb.Schedule, int64, error)
	Update(ctx context.Context, req *pb.UpdateScheduleRequest) (*pb.Schedule, error)
	Delete(ctx context.Context, name string) error
	Enable(ctx context.Context, name string) (*pb.Schedule, error)
	Disable(ctx context.Context, name string) (*pb.Schedule, error)
	Trigger(ctx context.Context, name string) (bool, string, error)
	History(ctx context.Context, name string, limit, offset int32) ([]*pb.ScheduleHistoryEntry, int64, error)
	Triggers(ctx context.Context) (<-chan *pb.ScheduleTrigger, error)
}

ScheduleHandler is the interface for schedule capability apps. Implement this to replace Nebo's built-in cron scheduler.

type ScheduleHistoryEntry 

type ScheduleHistoryEntry = pb.ScheduleHistoryEntry

ScheduleHistoryEntry represents one execution of a schedule.

type ScheduleTrigger 

type ScheduleTrigger = pb.ScheduleTrigger

ScheduleTrigger is emitted when a schedule fires.

type SchemaBuilder 

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

SchemaBuilder constructs JSON Schema for STRAP-pattern tool inputs.

func NewSchema 

func NewSchema(actions ...string) *SchemaBuilder

NewSchema creates a SchemaBuilder with the given action names. Actions become an enum on the required "action" field.

func (*SchemaBuilder) Bool 

func (s *SchemaBuilder) Bool(name, description string, required bool) *SchemaBuilder

Bool adds a boolean parameter to the schema.

func (*SchemaBuilder) Build 

func (s *SchemaBuilder) Build() json.RawMessage

Build returns the complete JSON Schema as json.RawMessage.

func (*SchemaBuilder) Enum 

func (s *SchemaBuilder) Enum(name, description string, required bool, values ...string) *SchemaBuilder

Enum adds a string enum parameter to the schema.

func (*SchemaBuilder) Number 

func (s *SchemaBuilder) Number(name, description string, required bool) *SchemaBuilder

Number adds a number parameter to the schema.

func (*SchemaBuilder) Object 

func (s *SchemaBuilder) Object(name, description string, required bool) *SchemaBuilder

Object adds an object parameter to the schema.

func (*SchemaBuilder) String 

func (s *SchemaBuilder) String(name, description string, required bool) *SchemaBuilder

String adds a string parameter to the schema.

type SelectOption 

type SelectOption struct {
	Label string
	Value string
}

SelectOption is a choice for select-type blocks.

type ToolHandler 

type ToolHandler interface {
	Name() string
	Description() string
	Schema() json.RawMessage
	Execute(ctx context.Context, input json.RawMessage) (string, error)
}

ToolHandler is the interface for tool capability apps. Implement this to give Nebo's agent a new tool.

type ToolHandlerWithApproval 

type ToolHandlerWithApproval interface {
	ToolHandler
	RequiresApproval() bool
}

ToolHandlerWithApproval is an optional extension for tools that require user confirmation.

type UIBlock 

type UIBlock struct {
	BlockID     string
	Type        string // text, heading, input, button, select, toggle, divider, image
	Text        string
	Value       string
	Placeholder string
	Hint        string
	Variant     string // button: primary/secondary/ghost/error; heading: h1/h2/h3
	Src         string // image source URL
	Alt         string // image alt text
	Disabled    bool
	Options     []SelectOption
	Style       string // compact, full-width
}

UIBlock is a single renderable element in a view.

type UIEvent 

type UIEvent struct {
	ViewID  string
	BlockID string
	Action  string // "click", "change", "submit"
	Value   string
}

UIEvent represents a user interaction with a UI block.

type UIEventResult 

type UIEventResult struct {
	View  *View  // Updated view (optional)
	Error string // Error message (optional)
	Toast string // Toast notification (optional)
}

UIEventResult is the response to a UI event.

type UIHandler 

type UIHandler interface {
	GetView(ctx context.Context, viewContext string) (*View, error)
	OnEvent(ctx context.Context, event UIEvent) (*UIEventResult, error)
}

UIHandler is the interface for UI capability apps. Implement this to render structured panels in Nebo's web interface.

type UIHandlerWithStreaming 

type UIHandlerWithStreaming interface {
	UIHandler
	StreamUpdates(ctx context.Context) (<-chan *View, error)
}

UIHandlerWithStreaming is an optional extension for apps that push live UI updates.

type View 

type View struct {
	ViewID string
	Title  string
	Blocks []UIBlock
}

View represents a complete renderable UI view.

type ViewBuilder 

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

ViewBuilder constructs a View with a fluent API.

func NewView 

func NewView(viewID, title string) *ViewBuilder

NewView creates a new ViewBuilder.

func (*ViewBuilder) Build 

func (v *ViewBuilder) Build() *View

Build returns the constructed View.

func (*ViewBuilder) Button 

func (v *ViewBuilder) Button(blockID, text, variant string) *ViewBuilder

Button adds a button block.

func (*ViewBuilder) Divider 

func (v *ViewBuilder) Divider(blockID string) *ViewBuilder

Divider adds a divider block.

func (*ViewBuilder) Heading 

func (v *ViewBuilder) Heading(blockID, text, variant string) *ViewBuilder

Heading adds a heading block.

func (*ViewBuilder) Image 

func (v *ViewBuilder) Image(blockID, src, alt string) *ViewBuilder

Image adds an image block.

func (*ViewBuilder) Input 

func (v *ViewBuilder) Input(blockID, value, placeholder string) *ViewBuilder

Input adds an input block.

func (*ViewBuilder) Select 

func (v *ViewBuilder) Select(blockID, value string, options []SelectOption) *ViewBuilder

Select adds a select block.

func (*ViewBuilder) Text 

func (v *ViewBuilder) Text(blockID, text string) *ViewBuilder

Text adds a text block.

func (*ViewBuilder) Toggle 

func (v *ViewBuilder) Toggle(blockID, text string, on bool) *ViewBuilder

Toggle adds a toggle block.

Source Files

View all Source files

Directories

Path Synopsis
examples
calculator command

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.