petalflow

package module
v0.4.0 Latest Latest
Warning

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

 Go to latest Published: Aug 3, 2026 License: MIT Imports: 6 Imported by: 0

README

PetalFlow

codecov

PetalFlow is an open-source Go workflow runtime for building AI agent systems as explicit, testable graphs. It helps you move from prompt experiments to production workflows with clear execution, reusable tools, webhook support, scheduling, event streams, and an HTTP daemon API.

Why PetalFlow

Use PetalFlow when you want your AI workflows to behave like software systems, not black boxes.

  • Build workflows as graphs with explicit nodes and edges.
  • Combine LLM steps, tool calls, routing, transforms, human gates, and webhooks.
  • Run workflows from Go code, the CLI, or an HTTP daemon.
  • Persist workflows, schedules, tools, and events in SQLite.
  • Stream and inspect runtime events for debugging and observability.
  • Export traces and metrics with OpenTelemetry.

Installation

Library
go get github.com/petal-labs/petalflow
CLI
go install github.com/petal-labs/petalflow/cmd/petalflow@latest

Quickstart (5 Minutes)

1. Run a workflow with no external services
petalflow run examples/06_cli_workflow/greeting.graph.json \
  --input '{"name":"World"}'

This executes a simple Graph IR workflow and prints the output envelope.

2. Validate and compile an Agent/Task workflow
petalflow validate examples/06_cli_workflow/research.agent.yaml
petalflow compile examples/06_cli_workflow/research.agent.yaml --output /tmp/research.graph.json
3. Run Agent/Task workflow with a provider key
export PETALFLOW_PROVIDER_ANTHROPIC_API_KEY=sk-ant-...
petalflow run examples/06_cli_workflow/research.agent.yaml \
  --input '{"topic":"Go concurrency patterns"}'

What You Can Build with PetalFlow

  • Customer support triage: classify inbound tickets, route by urgency, auto-draft replies.
  • Research and writing pipelines: gather information, summarize findings, draft final output.
  • Tool-driven automation: call internal APIs, databases, and MCP tools as workflow steps.
  • Human-in-the-loop approvals: pause at critical steps for explicit review.
  • Webhook automations: receive inbound events (webhook_trigger) and send outbound notifications (webhook_call).
  • Scheduled workflows: run recurring jobs via cron in daemon mode.

SDK Quickstart (Go)

package main

import (
	"context"
	"fmt"

	"github.com/petal-labs/petalflow"
)

func main() {
	g := petalflow.NewGraph("hello")

	greet := petalflow.NewFuncNode("greet", func(ctx context.Context, env *petalflow.Envelope) (*petalflow.Envelope, error) {
		name := env.GetVarString("name")
		env.SetVar("greeting", fmt.Sprintf("Hello, %s!", name))
		return env, nil
	})

	g.AddNode(greet)
	g.SetEntry("greet")

	env := petalflow.NewEnvelope().WithVar("name", "World")

	rt := petalflow.NewRuntime()
	result, err := rt.Run(context.Background(), g, env, petalflow.DefaultRunOptions())
	if err != nil {
		panic(err)
	}

	fmt.Println(result.GetVarString("greeting"))
}

CLI Overview

PetalFlow CLI supports two workflow formats:

  • Agent/Task (YAML/JSON): high-level authoring format.
  • Graph IR (JSON): low-level runtime graph format.
Core Commands
# Validate a workflow file
petalflow validate workflow.yaml

# Compile Agent/Task to Graph IR
petalflow compile workflow.yaml --output compiled.graph.json

# Run either Agent/Task or Graph IR
petalflow run workflow.yaml --input '{"topic":"AI agents"}'

# Start daemon API
petalflow serve --host 0.0.0.0 --port 8080
Provider Credentials

Provider resolution order:

  1. --provider-key flags
  2. Environment variables
  3. ~/.petalflow/config.json (or PETALFLOW_CONFIG)

Examples:

export PETALFLOW_PROVIDER_OPENAI_API_KEY=sk-...
export PETALFLOW_PROVIDER_ANTHROPIC_API_KEY=sk-ant-...

petalflow run workflow.yaml \
  --provider-key openai=sk-... \
  --input '{"topic":"Release notes"}'

Agent/Task Workflows (Simple Explanation)

Think of Agent/Task as a project plan for AI work:

  • agent = who does the work (role + model + provider)
  • task = what work gets done
  • execution = in what order tasks run
Real-World Mental Model
  • Research brief: One agent researches a topic, another writes a polished summary.
  • Incident response: One agent classifies severity, another drafts a mitigation plan.
  • Content operations: One agent outlines, another edits for tone and style.
Minimal Agent/Task Example
version: "1.0"
schema_version: "1.0.0"
kind: agent_workflow
id: research_workflow
name: Research Assistant

agents:
  researcher:
    role: Research Analyst
    goal: Gather useful facts about a topic
    provider: anthropic
    model: claude-sonnet-4-6

  writer:
    role: Technical Writer
    goal: Turn findings into a concise report
    provider: anthropic
    model: claude-sonnet-4-6

tasks:
  research:
    description: Research {{input.topic}} and summarize key points.
    agent: researcher
    expected_output: Structured notes

  write_report:
    description: Write a short report from {{tasks.research.output}}.
    agent: writer
    expected_output: Final report

execution:
  strategy: sequential
  task_order:
    - research
    - write_report

schema_version uses semantic versioning (MAJOR.MINOR.PATCH). Current supported major is 1. Legacy workflows without schema_version continue to load during the transition window for schema major 1; they are planned to be rejected when schema major 2 is introduced. Versioned JSON schema artifacts for editor/plugin tooling live in schemas/agent-workflow/v1.json and schemas/graph-workflow/v1.json.

Daemon API

Start daemon mode:

petalflow serve --host 0.0.0.0 --port 8080

Common endpoints:

  • POST /api/workflows/agent create workflow from Agent/Task
  • POST /api/workflows/graph create workflow from Graph IR
  • POST /api/workflows/{id}/run run a workflow
  • GET /api/workflows/{id}/schedules list cron schedules
  • POST /api/workflows/{id}/schedules create cron schedule
  • GET /api/runs/{run_id}/events fetch persisted run events

See full API docs: docs/daemon-api.md

Events and OpenTelemetry

PetalFlow emits structured runtime events like:

  • run.started, run.finished
  • node.started, node.finished, node.failed
  • tool.call, tool.result
  • route.decision
Event Streaming and Retrieval
  • CLI: petalflow run --stream streams node output events.
  • Daemon: run events are persisted and available at GET /api/runs/{run_id}/events.
OpenTelemetry Integration (SDK)
package main

import (
	"context"

	"github.com/petal-labs/petalflow"
	petalotel "github.com/petal-labs/petalflow/otel"
	sdkmetric "go.opentelemetry.io/otel/sdk/metric"
	sdktrace "go.opentelemetry.io/otel/sdk/trace"
)

func runWithTelemetry(ctx context.Context, g petalflow.Graph, env *petalflow.Envelope) error {
	tracerProvider := sdktrace.NewTracerProvider()
	meterProvider := sdkmetric.NewMeterProvider()

	tracing := petalotel.NewTracingHandler(tracerProvider.Tracer("petalflow"))
	metrics, err := petalotel.NewMetricsHandler(meterProvider.Meter("petalflow"))
	if err != nil {
		return err
	}

	opts := petalflow.DefaultRunOptions()
	opts.EventHandler = petalflow.MultiEventHandler(tracing.Handle, metrics.Handle)
	opts.EventEmitterDecorator = func(emit petalflow.EventEmitter) petalflow.EventEmitter {
		return petalotel.EnrichEmitter(emit, tracing)
	}

	_, err = petalflow.NewRuntime().Run(ctx, g, env, opts)
	return err
}

Webhooks

PetalFlow supports both directions of webhook automation:

  • webhook_trigger: start a workflow from an inbound HTTP webhook
  • webhook_call: send outbound HTTP webhook requests from a workflow

See full walk-through: examples/08_webhooks

Tools and MCP

PetalFlow includes a tool registry and MCP integration for attaching external capabilities to workflows.

Examples

Testing

# Root module tests
go test ./... -count=1

# Integration tests (requires provider key)
export OPENAI_API_KEY=sk-...
go test -tags=integration ./tests/integration/... -count=1 -v

Documentation

Repo docs live in docs/.

License

MIT. See LICENSE.

Documentation

Overview

Package petalflow provides a Go-native framework for building, orchestrating, and deploying AI agents and multimodal workflows.

This file provides backward-compatible re-exports for all types and constructors from the core, graph, runtime, and nodes subpackages. Existing code using petalflow.* imports will continue to work without modification.

For new code, consider importing subpackages directly for clearer dependencies: 

import "github.com/petal-labs/petalflow/core"
import "github.com/petal-labs/petalflow/graph"
import "github.com/petal-labs/petalflow/runtime"
import "github.com/petal-labs/petalflow/nodes"

Index

Constants

View Source 
const (
	NodeKindLLM            = core.NodeKindLLM
	NodeKindTool           = core.NodeKindTool
	NodeKindRouter         = core.NodeKindRouter
	NodeKindMerge          = core.NodeKindMerge
	NodeKindMap            = core.NodeKindMap
	NodeKindGate           = core.NodeKindGate
	NodeKindNoop           = core.NodeKindNoop
	NodeKindFilter         = core.NodeKindFilter
	NodeKindTransform      = core.NodeKindTransform
	NodeKindGuardian       = core.NodeKindGuardian
	NodeKindCache          = core.NodeKindCache
	NodeKindWebhookCall    = core.NodeKindWebhookCall
	NodeKindWebhookTrigger = core.NodeKindWebhookTrigger
	NodeKindHuman          = core.NodeKindHuman
)

NodeKind constants

View Source 
const (
	EventRunStarted    = runtime.EventRunStarted
	EventNodeStarted   = runtime.EventNodeStarted
	EventNodeOutput    = runtime.EventNodeOutput
	EventNodeFailed    = runtime.EventNodeFailed
	EventNodeFinished  = runtime.EventNodeFinished
	EventRouteDecision = runtime.EventRouteDecision
	EventRunFinished   = runtime.EventRunFinished
	EventStepPaused    = runtime.EventStepPaused
	EventStepResumed   = runtime.EventStepResumed
	EventStepSkipped   = runtime.EventStepSkipped
	EventStepAborted   = runtime.EventStepAborted
)

EventKind constants

View Source 
const (
	StepActionContinue        = runtime.StepActionContinue
	StepActionSkipNode        = runtime.StepActionSkipNode
	StepActionAbort           = runtime.StepActionAbort
	StepActionRunToBreakpoint = runtime.StepActionRunToBreakpoint
)

StepAction constants

View Source 
const (
	StepPointBeforeNode = runtime.StepPointBeforeNode
	StepPointAfterNode  = runtime.StepPointAfterNode
)

StepPoint constants

View Source 
const (
	OpEquals      = nodes.OpEquals
	OpNotEquals   = nodes.OpNotEquals
	OpContains    = nodes.OpContains
	OpGreaterThan = nodes.OpGreaterThan
	OpLessThan    = nodes.OpLessThan
	OpExists      = nodes.OpExists
	OpNotExists   = nodes.OpNotExists
	OpIn          = nodes.OpIn
)

ConditionOp constants

View Source 
const (
	GateActionBlock    = nodes.GateActionBlock
	GateActionSkip     = nodes.GateActionSkip
	GateActionRedirect = nodes.GateActionRedirect
)

GateAction constants

View Source 
const (
	FilterOpTopN      = nodes.FilterOpTopN
	FilterOpThreshold = nodes.FilterOpThreshold
	FilterOpDedupe    = nodes.FilterOpDedupe
	FilterOpByType    = nodes.FilterOpByType
	FilterOpMatch     = nodes.FilterOpMatch
	FilterOpExclude   = nodes.FilterOpExclude
	FilterOpCustom    = nodes.FilterOpCustom
)

FilterOpType constants

View Source 
const (
	FilterTargetArtifacts = nodes.FilterTargetArtifacts
	FilterTargetMessages  = nodes.FilterTargetMessages
	FilterTargetVar       = nodes.FilterTargetVar
)

FilterTarget constants

View Source 
const (
	TransformPick      = nodes.TransformPick
	TransformOmit      = nodes.TransformOmit
	TransformRename    = nodes.TransformRename
	TransformFlatten   = nodes.TransformFlatten
	TransformMerge     = nodes.TransformMerge
	TransformTemplate  = nodes.TransformTemplate
	TransformStringify = nodes.TransformStringify
	TransformParse     = nodes.TransformParse
	TransformMap       = nodes.TransformMap
	TransformCustom    = nodes.TransformCustom
)

TransformType constants

View Source 
const (
	GuardianCheckRequired  = nodes.GuardianCheckRequired
	GuardianCheckMaxLength = nodes.GuardianCheckMaxLength
	GuardianCheckMinLength = nodes.GuardianCheckMinLength
	GuardianCheckPattern   = nodes.GuardianCheckPattern
	GuardianCheckEnum      = nodes.GuardianCheckEnum
	GuardianCheckTypeCheck = nodes.GuardianCheckType_
	GuardianCheckRange     = nodes.GuardianCheckRange
	GuardianCheckPII       = nodes.GuardianCheckPII
	GuardianCheckSchema    = nodes.GuardianCheckSchema
	GuardianCheckCustom    = nodes.GuardianCheckCustom
)

GuardianCheckType constants

View Source 
const (
	GuardianActionFail     = nodes.GuardianActionFail
	GuardianActionSkip     = nodes.GuardianActionSkip
	GuardianActionRedirect = nodes.GuardianActionRedirect
)

GuardianAction constants

View Source 
const (
	PIITypeSSN         = nodes.PIITypeSSN
	PIITypeEmail       = nodes.PIITypeEmail
	PIITypePhone       = nodes.PIITypePhone
	PIITypeCreditCard  = nodes.PIITypeCreditCard
	PIITypeIPAddress   = nodes.PIITypeIPAddress
	PIITypeDateOfBirth = nodes.PIITypeDateOfBirth
)

PIIType constants

View Source 
const (
	HumanRequestApproval = nodes.HumanRequestApproval
	HumanRequestChoice   = nodes.HumanRequestChoice
	HumanRequestEdit     = nodes.HumanRequestEdit
	HumanRequestInput    = nodes.HumanRequestInput
	HumanRequestReview   = nodes.HumanRequestReview
)

HumanRequestType constants

View Source 
const (
	HumanTimeoutFail    = nodes.HumanTimeoutFail
	HumanTimeoutDefault = nodes.HumanTimeoutDefault
	HumanTimeoutSkip    = nodes.HumanTimeoutSkip
)

HumanTimeoutAction constants

View Source 
const (
	WebhookAuthTypeNone        = nodes.WebhookAuthTypeNone
	WebhookAuthTypeHeaderToken = nodes.WebhookAuthTypeHeaderToken
)

Webhook auth mode constants.

Variables

View Source 
var (
	NewEnvelope        = core.NewEnvelope
	NewBaseNode        = core.NewBaseNode
	NewNoopNode        = core.NewNoopNode
	NewFuncNode        = core.NewFuncNode
	NewFuncTool        = core.NewFuncTool
	NewToolRegistry    = core.NewToolRegistry
	DefaultRetryPolicy = core.DefaultRetryPolicy
)

Core package constructors

View Source 
var (
	ErrNodeNotFound     = graph.ErrNodeNotFound
	ErrDuplicateNode    = graph.ErrDuplicateNode
	ErrInvalidEdge      = graph.ErrInvalidEdge
	ErrNoEntryNode      = graph.ErrNoEntryNode
	ErrCycleDetected    = graph.ErrCycleDetected
	ErrEmptyGraph       = graph.ErrEmptyGraph
	ErrNodeAlreadyAdded = graph.ErrNodeAlreadyAdded
)

Graph package errors

View Source 
var (
	NewGraph          = graph.NewGraph
	NewGraphBuilder   = graph.NewGraphBuilder
	NewBranch         = graph.NewBranch
	NewPipelineBranch = graph.NewPipelineBranch
)

Graph package constructors

View Source 
var (
	ErrMaxHopsExceeded     = runtime.ErrMaxHopsExceeded
	ErrRunCanceled         = runtime.ErrRunCanceled
	ErrNodeExecution       = runtime.ErrNodeExecution
	ErrStepAborted         = runtime.ErrStepAborted
	ErrStepRequestNotFound = runtime.ErrStepRequestNotFound
)

Runtime package errors

View Source 
var (
	NewRuntime                  = runtime.NewRuntime
	DefaultRunOptions           = runtime.DefaultRunOptions
	NewEvent                    = runtime.NewEvent
	MultiEventHandler           = runtime.MultiEventHandler
	ChannelEventHandler         = runtime.ChannelEventHandler
	DefaultStepConfig           = runtime.DefaultStepConfig
	NewCallbackStepController   = runtime.NewCallbackStepController
	NewChannelStepController    = runtime.NewChannelStepController
	NewBreakpointStepController = runtime.NewBreakpointStepController
	NewAutoStepController       = runtime.NewAutoStepController
)

Runtime package constructors

View Source 
var (
	NewLLMNode                = nodes.NewLLMNode
	NewToolNode               = nodes.NewToolNode
	NewToolNodeWithRegistry   = nodes.NewToolNodeWithRegistry
	NewRuleRouter             = nodes.NewRuleRouter
	NewLLMRouter              = nodes.NewLLMRouter
	NewMergeNode              = nodes.NewMergeNode
	NewJSONMergeStrategy      = nodes.NewJSONMergeStrategy
	NewConcatMergeStrategy    = nodes.NewConcatMergeStrategy
	NewBestScoreMergeStrategy = nodes.NewBestScoreMergeStrategy
	NewFuncMergeStrategy      = nodes.NewFuncMergeStrategy
	NewAllMergeStrategy       = nodes.NewAllMergeStrategy
	NewMapNode                = nodes.NewMapNode
	NewFilterNode             = nodes.NewFilterNode
	NewTransformNode          = nodes.NewTransformNode
	NewGateNode               = nodes.NewGateNode
	NewCacheNode              = nodes.NewCacheNode
	NewMemoryCacheStore       = nodes.NewMemoryCacheStore
	NewCacheKeyBuilder        = nodes.NewCacheKeyBuilder
	NewMockNode               = nodes.NewMockNode
	NewGuardianNode           = nodes.NewGuardianNode
	NewHumanNode              = nodes.NewHumanNode
	NewChannelHumanHandler    = nodes.NewChannelHumanHandler
	NewCallbackHumanHandler   = nodes.NewCallbackHumanHandler
	NewAutoApproveHandler     = nodes.NewAutoApproveHandler
	NewAutoRejectHandler      = nodes.NewAutoRejectHandler
	NewQueuedHumanHandler     = nodes.NewQueuedHumanHandler
	NewWebhookCallNode        = nodes.NewWebhookCallNode
	NewWebhookTriggerNode     = nodes.NewWebhookTriggerNode
	NewMockHTTPClient         = nodes.NewMockHTTPClient
)

Nodes package constructors

Functions

This section is empty.

Types

type AllMergeStrategy 

type AllMergeStrategy = nodes.AllMergeStrategy

AllMergeStrategy collects all inputs into a single output.

type Artifact 

type Artifact = core.Artifact

Artifact represents a document or derived data produced during a run.

type AutoApproveHandler 

type AutoApproveHandler = nodes.AutoApproveHandler

AutoApproveHandler automatically approves or rejects requests.

type AutoStepController 

type AutoStepController = runtime.AutoStepController

AutoStepController automatically continues with a configurable delay.

type BaseNode 

type BaseNode = core.BaseNode

BaseNode provides common functionality for node implementations.

type BasicGraph 

type BasicGraph = graph.BasicGraph

BasicGraph is a simple implementation of the Graph interface.

type BasicRuntime 

type BasicRuntime = runtime.BasicRuntime

BasicRuntime is a simple sequential runtime implementation.

type BestScoreMergeConfig 

type BestScoreMergeConfig = nodes.BestScoreMergeConfig

BestScoreMergeConfig configures a BestScoreMergeStrategy.

type BestScoreMergeStrategy 

type BestScoreMergeStrategy = nodes.BestScoreMergeStrategy

BestScoreMergeStrategy selects the envelope with the best score.

type BreakpointStepController 

type BreakpointStepController = runtime.BreakpointStepController

BreakpointStepController only pauses at specified breakpoints.

type Budget 

type Budget = core.Budget

Budget is an optional guardrail for LLM calls to limit resource usage.

type CacheKeyBuilder 

type CacheKeyBuilder = nodes.CacheKeyBuilder

CacheKeyBuilder helps build complex cache keys.

type CacheNode 

type CacheNode = nodes.CacheNode

CacheNode wraps another node and caches its results.

type CacheNodeConfig 

type CacheNodeConfig = nodes.CacheNodeConfig

CacheNodeConfig configures a CacheNode.

type CacheResult 

type CacheResult = nodes.CacheResult

CacheResult contains metadata about a cache operation.

type CacheStore 

type CacheStore = nodes.CacheStore

CacheStore is the interface for cache storage backends.

type CallbackHumanHandler 

type CallbackHumanHandler = nodes.CallbackHumanHandler

CallbackHumanHandler uses a callback function.

type CallbackStepController 

type CallbackStepController = runtime.CallbackStepController

CallbackStepController invokes a function at each step.

type ChannelHumanHandler 

type ChannelHumanHandler = nodes.ChannelHumanHandler

ChannelHumanHandler uses Go channels for human interaction.

type ChannelStepController 

type ChannelStepController = runtime.ChannelStepController

ChannelStepController uses Go channels for interactive debugging.

type ConcatMergeConfig 

type ConcatMergeConfig = nodes.ConcatMergeConfig

ConcatMergeConfig configures a ConcatMergeStrategy.

type ConcatMergeStrategy 

type ConcatMergeStrategy = nodes.ConcatMergeStrategy

ConcatMergeStrategy merges by concatenating values.

type ConditionFunc 

type ConditionFunc = func(ctx context.Context, env *Envelope) (bool, error)

ConditionFunc is a convenience type for condition checking functions.

type ConditionOp 

type ConditionOp = nodes.ConditionOp

ConditionOp is the operator for a route condition.

type Edge 

type Edge = graph.Edge

Edge represents a directed connection between two nodes.

type EnvFunc 

type EnvFunc = func(ctx context.Context, env *Envelope) (*Envelope, error)

EnvFunc is a convenience type for envelope transformation functions.

type Envelope 

type Envelope = core.Envelope

Envelope is the single data structure passed between nodes.

func Run 

func Run(ctx context.Context, g Graph, env *Envelope) (*Envelope, error)

Run is a convenience function to execute a graph with default options. It creates a new runtime, runs the graph, and returns the result.

func RunParallel 

func RunParallel(ctx context.Context, g Graph, env *Envelope, concurrency int) (*Envelope, error)

RunParallel is a convenience function to execute a graph with parallel execution.

func RunWithHandler 

func RunWithHandler(ctx context.Context, g Graph, env *Envelope, handler EventHandler) (*Envelope, error)

RunWithHandler is a convenience function to execute a graph with an event handler.

func RunWithOptions 

func RunWithOptions(ctx context.Context, g Graph, env *Envelope, opts RunOptions) (*Envelope, error)

RunWithOptions is a convenience function to execute a graph with custom options.

type EnvelopeModification 

type EnvelopeModification = runtime.EnvelopeModification

EnvelopeModification specifies changes to apply to the envelope.

type EnvelopeSnapshot 

type EnvelopeSnapshot = runtime.EnvelopeSnapshot

EnvelopeSnapshot is a read-only view of the envelope state.

type Event 

type Event = runtime.Event

Event is a structured, streamable record of what happened during execution.

type EventEmitter 

type EventEmitter = runtime.EventEmitter

EventEmitter is a function type for emitting events.

type EventHandler 

type EventHandler = runtime.EventHandler

EventHandler is a function type for handling events.

type EventKind 

type EventKind = runtime.EventKind

EventKind identifies the type of event emitted by the runtime.

type FanOutBranch 

type FanOutBranch = graph.FanOutBranch

FanOutBranch is a helper for building complex fan-out patterns.

type FilterNode 

type FilterNode = nodes.FilterNode

FilterNode filters items based on conditions.

type FilterNodeConfig 

type FilterNodeConfig = nodes.FilterNodeConfig

FilterNodeConfig configures a FilterNode.

type FilterOp 

type FilterOp = nodes.FilterOp

FilterOp defines a filter operation.

type FilterOpType 

type FilterOpType = nodes.FilterOpType

FilterOpType is the type of filter operation.

type FilterStats 

type FilterStats = nodes.FilterStats

FilterStats tracks filter operation statistics.

type FilterTarget 

type FilterTarget = nodes.FilterTarget

FilterTarget specifies what to filter.

type FuncMergeStrategy 

type FuncMergeStrategy = nodes.FuncMergeStrategy

FuncMergeStrategy uses a custom function for merging.

type FuncNode 

type FuncNode = core.FuncNode

FuncNode wraps a function as a Node.

type FuncTool 

type FuncTool = core.FuncTool

FuncTool is a simple function-backed tool for PetalFlow.

type GateAction 

type GateAction = nodes.GateAction

GateAction defines what happens when a gate condition fails.

type GateNode 

type GateNode = nodes.GateNode

GateNode evaluates a condition and either passes execution or takes action.

type GateNodeConfig 

type GateNodeConfig = nodes.GateNodeConfig

GateNodeConfig configures a GateNode.

type GateResult 

type GateResult = nodes.GateResult

GateResult is stored in the envelope when ResultVar is set.

type Graph 

type Graph = graph.Graph

Graph represents a directed graph of nodes connected by edges.

func BuildGraph 

func BuildGraph(name string, nodes ...Node) (Graph, error)

BuildGraph is a convenience function to create a simple linear graph. It creates a builder, adds all nodes with edges between them, and builds.

func MustBuildGraph 

func MustBuildGraph(name string, nodes ...Node) Graph

MustBuildGraph is like BuildGraph but panics on error. Useful in tests and examples.

type GraphBuilder 

type GraphBuilder = graph.GraphBuilder

GraphBuilder provides a fluent API for constructing workflow graphs.

type GraphSnapshot 

type GraphSnapshot = runtime.GraphSnapshot

GraphSnapshot provides read-only graph context.

type GuardianAction 

type GuardianAction = nodes.GuardianAction

GuardianAction defines what happens when a check fails.

type GuardianCheck 

type GuardianCheck = nodes.GuardianCheck

GuardianCheck defines a validation check.

type GuardianCheckType 

type GuardianCheckType = nodes.GuardianCheckType

GuardianCheckType is the type of check to perform.

type GuardianFailure 

type GuardianFailure = nodes.GuardianFailure

GuardianFailure records a single check failure.

type GuardianNode 

type GuardianNode = nodes.GuardianNode

GuardianNode validates data against defined checks.

type GuardianNodeConfig 

type GuardianNodeConfig = nodes.GuardianNodeConfig

GuardianNodeConfig configures a GuardianNode.

type GuardianResult 

type GuardianResult = nodes.GuardianResult

GuardianResult contains the results of all checks.

type HTTPClient 

type HTTPClient = nodes.HTTPClient

HTTPClient is the interface for HTTP requests.

type HumanCallbackFunc 

type HumanCallbackFunc = func(ctx context.Context, req *HumanRequest) (*HumanResponse, error)

HumanCallbackFunc is a convenience type for human handler callbacks.

type HumanHandler 

type HumanHandler = nodes.HumanHandler

HumanHandler processes human requests.

type HumanNode 

type HumanNode = nodes.HumanNode

HumanNode requests human input or approval.

type HumanNodeConfig 

type HumanNodeConfig = nodes.HumanNodeConfig

HumanNodeConfig configures a HumanNode.

type HumanOption 

type HumanOption = nodes.HumanOption

HumanOption represents a choice option.

type HumanRequest 

type HumanRequest = nodes.HumanRequest

HumanRequest represents a request for human input.

type HumanRequestType 

type HumanRequestType = nodes.HumanRequestType

HumanRequestType identifies the type of human request.

type HumanResponse 

type HumanResponse = nodes.HumanResponse

HumanResponse contains the human's response.

type HumanTimeoutAction 

type HumanTimeoutAction = nodes.HumanTimeoutAction

HumanTimeoutAction defines what happens on timeout.

type JSONMergeConfig 

type JSONMergeConfig = nodes.JSONMergeConfig

JSONMergeConfig configures a JSONMergeStrategy.

type JSONMergeStrategy 

type JSONMergeStrategy = nodes.JSONMergeStrategy

JSONMergeStrategy merges envelopes by combining JSON data.

type LLMClient 

type LLMClient = core.LLMClient

LLMClient abstracts a single provider/model backend for PetalFlow.

type LLMMessage 

type LLMMessage = core.LLMMessage

LLMMessage is a chat message in PetalFlow format.

type LLMNode 

type LLMNode = nodes.LLMNode

LLMNode calls a language model to process the envelope.

type LLMNodeConfig 

type LLMNodeConfig = nodes.LLMNodeConfig

LLMNodeConfig configures an LLMNode.

type LLMReasoningOutput 

type LLMReasoningOutput = core.LLMReasoningOutput

LLMReasoningOutput contains reasoning information from the model.

type LLMRequest 

type LLMRequest = core.LLMRequest

LLMRequest is the request structure for LLM completion.

type LLMResponse 

type LLMResponse = core.LLMResponse

LLMResponse captures the output from an LLM call.

type LLMRouter 

type LLMRouter = nodes.LLMRouter

LLMRouter uses an LLM to make routing decisions.

type LLMRouterConfig 

type LLMRouterConfig = nodes.LLMRouterConfig

LLMRouterConfig configures an LLMRouter.

type LLMTokenUsage 

type LLMTokenUsage = core.LLMTokenUsage

LLMTokenUsage tracks token consumption for LLM calls.

type LLMToolCall 

type LLMToolCall = core.LLMToolCall

LLMToolCall represents a tool invocation requested by the model.

type LLMToolResult 

type LLMToolResult = core.LLMToolResult

LLMToolResult represents the result of executing a tool.

type MapNode 

type MapNode = nodes.MapNode

MapNode applies a sub-node to each item in a collection.

type MapNodeConfig 

type MapNodeConfig = nodes.MapNodeConfig

MapNodeConfig configures a MapNode.

type MemoryCacheStore 

type MemoryCacheStore = nodes.MemoryCacheStore

MemoryCacheStore is an in-memory cache implementation.

type MergeCapable 

type MergeCapable = core.MergeCapable

MergeCapable is implemented by nodes that can merge multiple input envelopes.

type MergeFunc 

type MergeFunc = func(ctx context.Context, inputs []*Envelope) (*Envelope, error)

MergeFunc is a convenience type for custom merge functions.

type MergeNode 

type MergeNode = nodes.MergeNode

MergeNode combines multiple input envelopes into one.

type MergeNodeConfig 

type MergeNodeConfig = nodes.MergeNodeConfig

MergeNodeConfig configures a MergeNode.

type MergeStrategy 

type MergeStrategy = nodes.MergeStrategy

MergeStrategy defines how to combine multiple envelopes.

type Message 

type Message = core.Message

Message is a chat-style message used for LLM steps and auditing.

type MockHTTPClient 

type MockHTTPClient = nodes.MockHTTPClient

MockHTTPClient is a mock HTTP client for testing.

type MockNode 

type MockNode = nodes.MockNode

MockNode is a simple node for testing.

type Node 

type Node = core.Node

Node is the fundamental unit of execution in a PetalFlow graph.

type NodeError 

type NodeError = core.NodeError

NodeError is recorded when nodes fail but the graph continues.

type NodeFunc 

type NodeFunc = core.NodeFunc

NodeFunc is a convenience type for node functions.

type NodeKind 

type NodeKind = core.NodeKind

NodeKind identifies the type of a node.

type NoopNode 

type NoopNode = core.NoopNode

NoopNode is a node that passes the envelope through unchanged.

type PIIType 

type PIIType = nodes.PIIType

PIIType identifies the type of PII detected.

type PetalTool 

type PetalTool = core.PetalTool

PetalTool is the tool interface for PetalFlow.

type QueuedHumanHandler 

type QueuedHumanHandler = nodes.QueuedHumanHandler

QueuedHumanHandler queues requests for later processing.

type RetryPolicy 

type RetryPolicy = core.RetryPolicy

RetryPolicy configures retry behavior for nodes that call external systems.

type RouteCondition 

type RouteCondition = nodes.RouteCondition

RouteCondition defines a condition for routing.

type RouteDecision 

type RouteDecision = core.RouteDecision

RouteDecision is produced by RouterNode to indicate which targets to activate.

type RouteRule 

type RouteRule = nodes.RouteRule

RouteRule defines a single routing rule.

type RouterNode 

type RouterNode = core.RouterNode

RouterNode is a node that can select which edges to activate.

type RuleRouter 

type RuleRouter = nodes.RuleRouter

RuleRouter routes based on configured rules.

type RuleRouterConfig 

type RuleRouterConfig = nodes.RuleRouterConfig

RuleRouterConfig configures a RuleRouter.

type RunOptions 

type RunOptions = runtime.RunOptions

RunOptions controls execution behavior.

func NewStepRunOptions 

func NewStepRunOptions(controller StepController) RunOptions

NewStepRunOptions creates RunOptions configured for step-through debugging.

func NewStepRunOptionsWithConfig 

func NewStepRunOptionsWithConfig(controller StepController, config *StepConfig) RunOptions

NewStepRunOptionsWithConfig creates RunOptions configured for step-through debugging with a custom step configuration.

func NewTimedRunOptions 

func NewTimedRunOptions(now func() time.Time) RunOptions

NewTimedRunOptions creates RunOptions with a custom time function. Useful for testing time-sensitive behavior.

type Runtime 

type Runtime = runtime.Runtime

Runtime executes graphs and emits events.

type ShouldPauseFunc 

type ShouldPauseFunc = runtime.ShouldPauseFunc

ShouldPauseFunc is an optional predicate for CallbackStepController.

type StepAction 

type StepAction = runtime.StepAction

StepAction specifies what the runtime should do at a step point.

type StepCallback 

type StepCallback = runtime.StepCallback

StepCallback is the function signature for CallbackStepController.

type StepConfig 

type StepConfig = runtime.StepConfig

StepConfig configures step-through behavior.

type StepController 

type StepController = runtime.StepController

StepController is the interface for controlling step-through execution.

type StepHandler 

type StepHandler = runtime.StepHandler

StepHandler is called when a breakpoint is hit.

type StepPoint 

type StepPoint = runtime.StepPoint

StepPoint indicates when a step pause occurred.

type StepRequest 

type StepRequest = runtime.StepRequest

StepRequest contains information about the current step point.

type StepResponse 

type StepResponse = runtime.StepResponse

StepResponse contains the controller's decision.

type StreamChunk added in v0.3.0 

type StreamChunk = core.StreamChunk

StreamChunk is a partial response from the LLM.

type StreamingLLMClient added in v0.3.0 

type StreamingLLMClient = core.StreamingLLMClient

StreamingLLMClient extends LLMClient with streaming capability.

type TokenUsage 

type TokenUsage = core.TokenUsage

TokenUsage tracks token consumption for cost tracking and budgeting.

type ToolNode 

type ToolNode = nodes.ToolNode

ToolNode executes a tool and stores the result.

type ToolNodeConfig 

type ToolNodeConfig = nodes.ToolNodeConfig

ToolNodeConfig configures a ToolNode.

type ToolRegistry 

type ToolRegistry = core.ToolRegistry

ToolRegistry holds a collection of tools for lookup by name.

type TraceInfo 

type TraceInfo = core.TraceInfo

TraceInfo is propagated by the runtime for observability and replay.

type TransformFunc 

type TransformFunc = func(ctx context.Context, env *Envelope) (*Envelope, error)

TransformFunc is a convenience type for custom transformation functions.

type TransformNode 

type TransformNode = nodes.TransformNode

TransformNode reshapes or transforms data.

type TransformNodeConfig 

type TransformNodeConfig = nodes.TransformNodeConfig

TransformNodeConfig configures a TransformNode.

type TransformType 

type TransformType = nodes.TransformType

TransformType specifies the type of transformation.

type ValidateFunc 

type ValidateFunc = func(ctx context.Context, env *Envelope, check *GuardianCheck) (bool, string, error)

ValidateFunc is a convenience type for custom validation functions.

type WebhookAuthType added in v0.3.0 

type WebhookAuthType = nodes.WebhookAuthType

WebhookAuthType identifies webhook trigger auth mode.

type WebhookCallNode added in v0.3.0 

type WebhookCallNode = nodes.WebhookCallNode

WebhookCallNode executes outbound HTTP webhook calls.

type WebhookCallNodeConfig added in v0.3.0 

type WebhookCallNodeConfig = nodes.WebhookCallNodeConfig

WebhookCallNodeConfig configures a WebhookCallNode.

type WebhookTriggerAuthConfig added in v0.3.0 

type WebhookTriggerAuthConfig = nodes.WebhookTriggerAuthConfig

WebhookTriggerAuthConfig configures webhook trigger authentication.

type WebhookTriggerNode added in v0.3.0 

type WebhookTriggerNode = nodes.WebhookTriggerNode

WebhookTriggerNode maps inbound webhook requests into workflow vars.

type WebhookTriggerNodeConfig added in v0.3.0 

type WebhookTriggerNodeConfig = nodes.WebhookTriggerNodeConfig

WebhookTriggerNodeConfig configures a WebhookTriggerNode.

Source Files

View all Source files

Directories

Path Synopsis
Package bus provides an event distribution system for PetalFlow workflow execution.
 Package bus provides an event distribution system for PetalFlow workflow execution.
cmd
petalflow command
Package core provides the foundational types and interfaces for PetalFlow workflows.
 Package core provides the foundational types and interfaces for PetalFlow workflows.
Package graph provides the directed graph model for PetalFlow workflows.
 Package graph provides the directed graph model for PetalFlow workflows.
internal
sqldialect
Package llmprovider bridges iris LLM providers to petalflow's core.LLMClient interface.
 Package llmprovider bridges iris LLM providers to petalflow's core.LLMClient interface.
Package loader provides schema detection and loading for PetalFlow workflow files.
 Package loader provides schema detection and loading for PetalFlow workflow files.
Package nodes provides the node implementations for PetalFlow workflows.
 Package nodes provides the node implementations for PetalFlow workflows.
conditional
Package conditional implements the conditional routing node for PetalFlow.
 Package conditional implements the conditional routing node for PetalFlow.
conditional/expr
Package expr provides a minimal, safe expression language for conditional routing in PetalFlow graphs.
 Package expr provides a minimal, safe expression language for conditional routing in PetalFlow graphs.
Package otel provides OpenTelemetry integration for PetalFlow runtime events.
 Package otel provides OpenTelemetry integration for PetalFlow runtime events.
Package registry provides a global node-type registry for PetalFlow.
 Package registry provides a global node-type registry for PetalFlow.
Package runtime provides the execution engine for PetalFlow workflow graphs.
 Package runtime provides the execution engine for PetalFlow workflow graphs.
Package sse provides a Server-Sent Events handler for streaming workflow execution events to HTTP clients.
 Package sse provides a Server-Sent Events handler for streaming workflow execution events to HTTP clients.
Package tool defines the contract boundary for external tool integration.
 Package tool defines the contract boundary for external tool integration.
mcp
Package mcp implements the core Model Context Protocol client primitives used by PetalFlow tool adapters.
 Package mcp implements the core Model Context Protocol client primitives used by PetalFlow tool adapters.
Package traceflow provides the PetalTrace SDK adapter for enriching PetalFlow execution traces with observability data.
 Package traceflow provides the PetalTrace SDK adapter for enriching PetalFlow execution traces with observability data.

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.