Master the fundamentals

// Builder is for construction - define nodes and edges
b := graph.New(keys...)
b.Node("fetch", fetchFunc, "process")
b.Start("fetch")

// Graph is the compiled executor - run the workflow
compiled, err := b.Build()  // Validates and compiles
if err != nil {
    return err
}

// Only compiled Graph has Run()
for output, err := range compiled.Run(ctx, input) {
    // process outputs...
}

// Graph.Run returns an iterator of outputs
func (g *Graph) Run(ctx context.Context, input []message.Message, opts ...RunOption) iter.Seq2[message.Message, error]

// GraphBuilder is a builder for message-processing workflows
type GraphBuilder = graph.Builder

// Graph is an executable message-processing workflow
type Graph = graph.Graph

import (
    "github.com/hupe1980/agentmesh/pkg/agent"
    "github.com/hupe1980/agentmesh/pkg/message"
)

// Agent constructors return *message.Graph (ready to run)
reactAgent, err := agent.NewReAct(model, agent.WithTools(tools...))
if err != nil {
    return err
}

// Execute with iterator pattern - no Build() needed!
for msg, err := range reactAgent.Run(ctx, messages) {
    if err != nil {
        return err
    }
    fmt.Println(msg.Content())
}

// ✅ Type-safe: message.Graph accepts []message.Message
reactAgent.Run(ctx, messages)

// ❌ Compile error: won't accept wrong input type
reactAgent.Run(ctx, "invalid input")

// ❌ Compile error: can't run uncompiled builder
b := message.NewGraphBuilder()
b.Run(ctx, messages)  // Error: Builder has no Run method

// All agents are *message.Graph - compose freely
worker1, _ := agent.NewReAct(model)
worker2, _ := agent.NewReAct(model)
supervisor, _ := agent.NewSupervisor(model,
    agent.WithWorker("researcher", "Does research", worker1),
    agent.WithWorker("writer", "Writes content", worker2),
)

import "github.com/hupe1980/agentmesh/pkg/graph"

// Define typed state keys (zero value is automatic)
var (
    RawDataKey       = graph.NewKey[string]("raw_data")
    ProcessedDataKey = graph.NewKey[string]("processed_data")
    StatusKey        = graph.NewKey[string]("status")
)

// Create graph with state keys
g := graph.New(RawDataKey, ProcessedDataKey, StatusKey)

// Add nodes with fluent API - targets are declared inline
g.Node("fetch", fetchDataFunc, "process").
  Node("process", processDataFunc, "save").
  Node("save", saveDataFunc, graph.END).
  Start("fetch")

// Compile into executable graph
compiled, err := g.Build()
if err != nil {
    return err
}

// Run the graph
for output, err := range compiled.Run(ctx, "input data") {
    if err != nil {
        return err
    }
    fmt.Println(output)
}

// NodeFunc signature
type NodeFunc func(ctx context.Context, scope Scope) (*Command, error)

// Example node function
func processDataFunc(ctx context.Context, scope graph.Scope) (*graph.Command, error) {
    // Read from state using typed keys
    rawData := graph.Get(scope, RawDataKey)
    
    // Process the data
    processed := strings.ToUpper(rawData)
    
    // Return updates and next target using fluent API
    return graph.Set(ProcessedDataKey, processed).
        Set(StatusKey, "processed").
        To("save"), nil
}

var CategoryKey = graph.NewKey[string]("category")

func classifierFunc(ctx context.Context, scope graph.Scope) (*graph.Command, error) {
    category := graph.Get(scope, CategoryKey)
    
    switch category {
    case "urgent":
        return graph.To("urgent_handler"), nil
    case "normal":
        return graph.To("normal_handler"), nil
    default:
        return graph.To("default_handler"), nil
    }
}

// Node declares all possible targets
g.Node("classifier", classifierFunc, "urgent_handler", "normal_handler", "default_handler")

import "github.com/hupe1980/agentmesh/pkg/graph"

// Key[T] - single value with ReplaceReducer (last write wins)
var (
    CounterKey = graph.NewKey[int]("counter")
    StatusKey  = graph.NewKey[string]("status")
)

// ListKey[T] - append-only list with AppendReducer
var MessagesKey = graph.NewListKey[message.Message]("messages")

// CounterKey - sum reducer for numeric accumulation
var TotalKey = graph.NewCounterKey("total")

// MapKey - merge reducer for map values
var MetadataKey = graph.NewMapKey[string, any]("metadata")

func myNode(ctx context.Context, scope graph.Scope) (*graph.Command, error) {
    // Type-safe reads - returns the correct type
    counter := graph.Get(scope, CounterKey)      // int
    status := graph.Get(scope, StatusKey)        // string
    messages := graph.GetList(scope, MessagesKey) // []message.Message
    
    return graph.To("next_node"), nil
}

func myNode(ctx context.Context, scope graph.Scope) (*graph.Command, error) {
    counter := graph.Get(scope, CounterKey)
    
    // Fluent, type-safe updates
    return graph.Set(CounterKey, counter + 1).
        With(graph.SetValue(StatusKey, "processing")).
        To("next_node")
}

// For list keys, Set with a slice - the reducer handles appending
func addMessageNode(ctx context.Context, scope graph.Scope) (*graph.Command, error) {
    newMsg := message.NewAIMessage(message.NewTextPart("Hello!"))
    
    return graph.Set(MessagesKey, []message.Message{newMsg}).
        To("next_node")
}

// Custom reducer example
var HighScoreKey = graph.NewKey[int]("high_score", 
    graph.WithReducer(graph.MaxReducer[int]{}))  // Keep maximum value

var LogsKey = graph.NewListKey[string]("logs",
    graph.WithReducer(graph.PrependReducer[string]{}))  // Insert at front

// Creates a graph with MessagesKey pre-registered
g := message.NewGraphBuilder()

// MessagesKey is available
g.Node("chat", func(ctx context.Context, scope graph.Scope) (*graph.Command, error) {
    messages := message.GetMessages(scope)
    // ... process messages
    return graph.Set(message.MessagesKey, []message.Message{response}).To(graph.END), nil
}, graph.END)

g := graph.New(ResultKey)

// Entry node fans out to three parallel tasks
g.Node("start", func(ctx context.Context, scope graph.Scope) (*graph.Command, error) {
    return graph.To("fetch_a", "fetch_b", "fetch_c"), nil
}, "fetch_a", "fetch_b", "fetch_c")

// Each fetch task routes to aggregator
g.Node("fetch_a", fetchAFunc, "aggregator").
  Node("fetch_b", fetchBFunc, "aggregator").
  Node("fetch_c", fetchCFunc, "aggregator").
  Node("aggregator", aggregateFunc, graph.END).
  Start("start")

var (
    DraftKey     = graph.NewKey[string]("draft")
    IterationKey = graph.NewCounterKey("iteration")  // Sum reducer for incrementing
)

func writerFunc(ctx context.Context, scope graph.Scope) (*graph.Command, error) {
    iteration := graph.Get(scope, IterationKey)
    draft := generateDraft(iteration)
    
    return graph.Set(DraftKey, draft).
        Set(IterationKey, iteration + 1).
        To("evaluator"), nil
}

func evaluatorFunc(ctx context.Context, scope graph.Scope) (*graph.Command, error) {
    draft := graph.Get(scope, DraftKey)
    iteration := graph.Get(scope, IterationKey)
    
    if isGoodEnough(draft) || iteration >= 5 {
        return graph.To(graph.END), nil
    }
    // Loop back for refinement
    return graph.To("writer"), nil
}

g := graph.New(DraftKey, IterationKey)
g.Node("writer", writerFunc, "evaluator").
  Node("evaluator", evaluatorFunc, graph.END, "writer"). // declares both targets
  Start("writer")

for output, err := range compiled.Run(ctx, input, 
    graph.WithMaxIterations(10),
) {
    // ...
}

import "github.com/hupe1980/agentmesh/pkg/message"

// Human input (simple text)
humanMsg := message.NewHumanMessageFromText("What's the weather?")

// AI response (simple text)
aiMsg := message.NewAIMessageFromText("It's sunny and 72°F")

// System prompt (simple text)
systemMsg := message.NewSystemMessageFromText("You are a helpful assistant")

// For multi-part messages, use Parts slice
multiPart := message.NewHumanMessage([]message.Part{
    message.TextPart{Text: "Describe this image:"},
    message.FilePart{MimeType: "image/png", File: message.FileURI{URI: imageURL}},
})

// Tool call
toolCall := message.ToolCall{
    ID:        "call_123",
    Name:      "get_weather",
    Type:      "function",
    Arguments: `{"location":"Paris"}`,  // JSON string
}
aiWithTool := message.NewAIMessage(
    []message.Part{message.TextPart{Text: "Let me check"}},
    message.WithToolCalls(toolCall),
)

// Tool result
toolMsg := message.NewToolMessage("call_123", "Sunny, 22°C")

aiMsg := message.NewAIMessage([]message.Part{
    message.TextPart{Text: "Here's the weather"},
    message.FilePart{
        MimeType: "image/png",
        File:     message.FileURI{URI: imageURL},
    },
})

// Quick text extraction using String()
fmt.Println(aiMsg.String()) // "Here's the weather[file: (image/png)]"

// Access individual parts when you need type-specific handling
for _, part := range aiMsg.Parts() {
    switch p := part.(type) {
    case message.TextPart:
        fmt.Println("Text:", p.Text)
    case message.FilePart:
        fmt.Println("File:", p.Name, p.MimeType)
    }
}

import "github.com/hupe1980/agentmesh/pkg/graph"

for output, err := range compiled.Run(ctx, input) {
    if err != nil {
        switch {
        case errors.Is(err, graph.ErrNotBuilt):
            log.Error("Graph not compiled - call Build() first")
            
        case errors.Is(err, graph.ErrNoEntryPoint):
            log.Error("No entry point set - call Start()")
            
        case errors.Is(err, graph.ErrNodeNotFound):
            log.Error("Referenced node doesn't exist")
            
        case errors.Is(err, graph.ErrDuplicateNode):
            log.Error("Node name already used")
            
        case errors.Is(err, graph.ErrDuplicateKey):
            log.Error("State key name already registered")
            
        default:
            return err
        }
    }
}

var interruptErr *graph.InterruptError
if errors.As(err, &interruptErr) {
    fmt.Printf("Interrupted at node %s (before=%v)\n", 
        interruptErr.NodeName, interruptErr.Before)
    
    // Resume with approval (WithApproval is a ResumeOption)
    for output, err := range compiled.Resume(ctx, runID,
        graph.WithApproval(interruptErr.NodeName, &graph.ApprovalResponse{
            Decision: graph.ApprovalApproved,
        }),
    ) {
        // ...
    }
}