gonostic

https://github.com/sultanfariz/gonostic
Admin
A Go framework for building AI agent systems with tool use, orchestration, and async execution.
Tokens:2,583
Snippets:35
Trust Score:8
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install Gonostic

Source: https://github.com/sultanfariz/gonostic/blob/main/README.md

Install the gonostic library using go get.

```bash
go get github.com/sultanfariz/gonostic
```

--------------------------------

### Example ModelProvider Implementation

Source: https://github.com/sultanfariz/gonostic/blob/main/README.md

An example implementation of the Complete method for the ModelProvider interface. It shows how to handle optional parameters like OutputSchema and Temperature.

```go
func (p *MyProvider) Complete(ctx context.Context, req *CompletionRequest) (*ModelResponse, error) {
    // Use req.OutputSchema for structured output if provided
    if len(req.OutputSchema) > 0 {
        // Configure your LLM for structured output
    }
    // Use req.Temperature if provided
    if req.Temperature != nil {
        // Apply temperature setting
    }
    // Process req.Files for multimodal input
    // ... implementation
}
```

--------------------------------

### Get Task Status

Source: https://github.com/sultanfariz/gonostic/blob/main/README.md

Retrieves the current status of an asynchronous task using its task ID. Possible statuses include JobPending, JobRunning, JobCompleted, and JobFailed.

```go
// Check status
status, _ := exec.GetStatus(taskID)
// JobPending | JobRunning | JobCompleted | JobFailed
```

--------------------------------

### Create LLMAgent with Tools

Source: https://github.com/sultanfariz/gonostic/blob/main/README.md

Demonstrates how to instantiate an LLMAgent with a name, prompt, model provider, and a list of available tools. The agent can then execute tasks.

```go
agent := agent.NewLLMAgent(agent.LLMAgentConfig{
    Name:   "assistant",
    Prompt: "You are a helpful assistant. User context: {user_name}",
    Model:  myModelProvider, // implements ModelProvider interface
    Tools:  []agent.Tool{searchTool, calcTool},
    MaxTurns: 10,
})

result, err := agent.Execute(ctx, task)
```

--------------------------------

### Task and Result Structures

Source: https://github.com/sultanfariz/gonostic/blob/main/README.md

Illustrates the creation of a Task object with input, files, parameters, and execution configuration, and how to process the Result, including output, success status, metrics, and execution steps.

```go
// Task is the input to an agent
task := &agent.Task{
    ID:     "task-123",
    Input:  "Summarize this document",
    Files:  []agent.FileInput{imageFile}, // Optional multimodal inputs
    Params: map[string]interface{}{"format": "bullet"},
    State:  make(map[string]interface{}),
    Config: &agent.ExecutionConfig{
        MaxIterations:  5,
        TimeoutSeconds: 60,
        Temperature:    0.7, // Passed to model provider
    },
}

// Result contains output, artifacts, execution audit trail, and metrics
result, err := myAgent.Execute(ctx, task)
fmt.Println(result.Output)
fmt.Println(result.Success)

// Metrics tracking
fmt.Printf("Tokens: %d, LLM Latency: %v\n",
    result.TotalTokenUsage.TotalTokens, result.TotalLLMLatency)

for _, step := range result.Steps {
    fmt.Printf("%s: %s (%v)\n", step.AgentName, step.Action, step.Duration)
}
```

--------------------------------

### Create and Use MapState for Session Agents

Source: https://github.com/sultanfariz/gonostic/blob/main/README.md

Demonstrates the creation of a thread-safe MapState object and how to set and retrieve key-value pairs for managing session state.

```go
state := agent.NewMapState()
state.Set("user_id", "123")
```

--------------------------------

### Create LLMAgent with Structured Output Schema

Source: https://github.com/sultanfariz/gonostic/blob/main/README.md

Shows how to configure an LLMAgent to enforce a JSON schema on its responses, useful for extracting structured data.

```go
agent := agent.NewLLMAgent(agent.LLMAgentConfig{
    Name:   "extractor",
    Prompt: "Extract user information from text",
    OutputSchema: map[string]interface{}{
        "type": "object",
        "properties": map[string]interface{}{
            "name": map[string]interface{}{"type": "string"},
            "age":  map[string]interface{}{"type": "integer"},
        },
        "required": []string{"name", "age"},
    },
    Model: myModelProvider,
})
```

--------------------------------

### Create PipelineAgent

Source: https://github.com/sultanfariz/gonostic/blob/main/README.md

Initializes a PipelineAgent that chains agents sequentially, where the output of one agent serves as the input for the next in the chain.

```go
pipeline := agent.NewPipelineAgent("etl", []agent.Agent{
    extractAgent,  // output: raw data
    transformAgent, // input: raw data, output: cleaned data
    loadAgent,      // input: cleaned data
})
```

--------------------------------

### Initialize Executor for Async Execution

Source: https://github.com/sultanfariz/gonostic/blob/main/README.md

Sets up an Executor with a specified number of workers to manage the asynchronous execution of agents and tasks.

```go
exec := agent.NewExecutor(myAgent, 5) // 5 workers
```

--------------------------------

### Create SequentialAgent

Source: https://github.com/sultanfariz/gonostic/blob/main/README.md

Instantiates a SequentialAgent that runs a series of agents in a defined order, passing the accumulated state from one to the next.

```go
pipeline := agent.NewSequentialAgent("data-pipeline", []agent.Agent{
    fetchAgent,
    transformAgent,
    storeAgent,
})
```

--------------------------------

### Create a TieredProvider with Retries and Fallbacks

Source: https://github.com/sultanfariz/gonostic/blob/main/README.md

Instantiate a TieredProvider to wrap multiple model providers with automatic retries and tiered fallback mechanisms. Configure retry settings using agent.DefaultRetryConfig().

```go
tiered := agent.NewTieredProvider(
    [][]agent.ModelProvider{
        {primary, backup}, // tier 0
        {fallback},        // tier 1
    },
    agent.DefaultRetryConfig(), // 2 retries, 500ms initial, 2× backoff, 10s cap
)

// Drop-in replacement for any ModelProvider
myAgent := agent.NewLLMAgent(agent.LLMAgentConfig{Model: tiered, ...})
```

--------------------------------

### Tool Interface Definition

Source: https://github.com/sultanfariz/gonostic/blob/main/README.md

Defines the interface for tools that agents can invoke, including methods for naming, description, schema definition, and execution.

```go
type Tool interface {
    Name() string
    Description() string
    Schema() interface{}
    Execute(ctx context.Context, args map[string]interface{}) (interface{}, error)
}
```

--------------------------------

### Agent Interface Definition

Source: https://github.com/sultanfariz/gonostic/blob/main/README.md

Defines the core interface that all agents must implement, including methods for naming, execution, and managing sub-agents.

```go
type Agent interface {
    Name() string
    Execute(ctx context.Context, task *Task) (*Result, error)
    SubAgents() []Agent
}
```

--------------------------------

### Define the ModelProvider Interface

Source: https://github.com/sultanfariz/gonostic/blob/main/README.md

The ModelProvider interface is required for using LLMAgent. It defines the Complete method for processing completion requests.

```go
type ModelProvider interface {
    Complete(ctx context.Context, req *CompletionRequest) (*ModelResponse, error)
}
```

--------------------------------

### Create Invocation for SessionAgent Run

Source: https://github.com/sultanfariz/gonostic/blob/main/README.md

Constructs an Invocation object for a SessionAgent's Run method, including session details, user input, state, and run configuration.

```go
inv := &agent.Invocation{
    SessionID: "session-abc",
    UserID:    "user-123",
    Input:     &agent.Message{Role: "user", Content: "Hello"},
    State:     state,
    Config: &agent.RunConfig{
        MaxIterations: 10,
        StreamingMode: agent.StreamingModeFull,
        EnableMemory:  true,
    },
}
```

--------------------------------

### Create ParallelAgent

Source: https://github.com/sultanfariz/gonostic/blob/main/README.md

Creates a ParallelAgent that executes multiple agents concurrently. Each agent operates with its own isolated state, and the final result aggregates their outputs.

```go
parallel := agent.NewParallelAgent("multi-search", []agent.Agent{
    webSearchAgent,
    dbSearchAgent,
    cacheSearchAgent,
})

// Result.Output is map[string]interface{} with each agent's output
```

--------------------------------

### Execute Task Synchronously

Source: https://github.com/sultanfariz/gonostic/blob/main/README.md

Executes a task synchronously using the Executor, blocking until the result is available.

```go
// Or execute synchronously
result, err := exec.ExecuteSync(ctx, "Process this", params)
```

--------------------------------

### Define the CompletionRequest Struct

Source: https://github.com/sultanfariz/gonostic/blob/main/README.md

The CompletionRequest struct contains all parameters for a model completion task, including prompt, files, tools, history, and output schema.

```go
type CompletionRequest struct {
    Prompt       string                 // User input prompt
    Files        []FileInput            // Multimodal inputs (images, PDFs)
    Tools        []Tool                 // Available function calling tools
    History      []Message              // Conversation history
    OutputSchema map[string]interface{} // JSON schema for structured output
    Temperature  *float32               // Sampling temperature (nil = use default)
    MaxTokens    *int                   // Max completion tokens (nil = use default)
}
```

--------------------------------

### SessionAgent Interface Definition

Source: https://github.com/sultanfariz/gonostic/blob/main/README.md

Defines the interface for session-based agents, which are designed for interactive, stateful conversations and manage their own state.

```go
type SessionAgent interface {
    Name() string
    Run(ctx context.Context, inv *Invocation) (*Response, error)
    Agents() []SessionAgent
}
```

--------------------------------

### Submit Task Asynchronously

Source: https://github.com/sultanfariz/gonostic/blob/main/README.md

Submits a task to the Executor for asynchronous processing, returning a task ID for status tracking.

```go
// Async submission
taskID, _ := exec.Submit("Process this", params, config)
```

--------------------------------

### Define the ModelResponse Struct

Source: https://github.com/sultanfariz/gonostic/blob/main/README.md

The ModelResponse struct holds the output from a model completion, including content, tool calls, reasoning, and token usage.

```go
type ModelResponse struct {
    Content   string
    ToolCalls []ToolCall
    Reasoning string
    Finished  bool
    Usage     *TokenUsage // Token usage metadata
}
```

--------------------------------

### Retrieve Task Result (Blocking)

Source: https://github.com/sultanfariz/gonostic/blob/main/README.md

Fetches the result of an asynchronous task. This call will block until the task is completed or fails.

```go
// Get result (blocks until complete)
result, err := exec.GetResult(taskID)
```

--------------------------------

### Implement RetryableError for Custom Errors

Source: https://github.com/sultanfariz/gonostic/blob/main/README.md

Define a custom error type that implements the Retryable() method to signal permanent failures. This prevents the framework from retrying or falling back on these specific errors.

```go
func (e *MyError) Retryable() bool { return e.StatusCode == 429 || e.StatusCode >= 500 }
```
Tokens:
Raw